From 0aa14ae363c66dc13d931729945bc85d80c6cacd Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 5 Dec 2007 21:41:07 +0000
Subject: [PATCH] Scribble improvements: defmodule & co.

svn: r7902

original commit: cd7157641cc8a1dd6266c926675e5909daeb643f
---
 collects/scribble/decode.ss                   |   5 +-
 collects/scribble/doc/lang/reader.ss          |   2 +-
 collects/scribble/doc/main.ss                 |   6 +
 .../scribble/{docreader.ss => doc/reader.ss}  |   4 +-
 collects/scribble/latex-render.ss             |   1 +
 collects/scribble/manual-struct.ss            |   1 +
 collects/scribble/manual.ss                   |  87 ++++++++++-
 collects/scribble/scribble.css                |  10 ++
 collects/scribblings/scribble/basic.scrbl     |  12 +-
 collects/scribblings/scribble/bnf.scrbl       |  59 +++++++
 collects/scribblings/scribble/decode.scrbl    |  24 +--
 collects/scribblings/scribble/doclang.scrbl   |  13 +-
 collects/scribblings/scribble/docreader.scrbl |  11 +-
 collects/scribblings/scribble/eval.scrbl      |   9 +-
 collects/scribblings/scribble/how-to.scrbl    | 145 ++++++++++++------
 collects/scribblings/scribble/manual.scrbl    |  80 ++++++++--
 collects/scribblings/scribble/reader.scrbl    |  11 +-
 collects/scribblings/scribble/renderer.scrbl  |  35 +++--
 collects/scribblings/scribble/scheme.scrbl    |  12 ++
 collects/scribblings/scribble/scribble.scrbl  |  53 +++----
 collects/scribblings/scribble/struct.scrbl    |   2 +-
 21 files changed, 439 insertions(+), 143 deletions(-)
 create mode 100644 collects/scribble/doc/main.ss
 rename collects/scribble/{docreader.ss => doc/reader.ss} (89%)
 create mode 100644 collects/scribblings/scribble/bnf.scrbl
 create mode 100644 collects/scribblings/scribble/scheme.scrbl

diff --git a/collects/scribble/decode.ss b/collects/scribble/decode.ss
index af2affd3..0b11accc 100644
--- a/collects/scribble/decode.ss
+++ b/collects/scribble/decode.ss
@@ -26,7 +26,8 @@
    [splice ([run list?])]
    [part-index-decl ([plain-seq (listof string?)]
                      [entry-seq list?])]
-   [part-collect-decl ([element element?])])
+   [part-collect-decl ([element element?])]
+   [part-tag-decl ([tag tag?])])
 
   (define (decode-string s)
     (let loop ([l '((#rx"---" mdash)
@@ -173,6 +174,8 @@
         (loop (cdr l) next? (cons (car l) keys) colls accum title tag-prefix tags style)]
        [(part-collect-decl? (car l))
         (loop (cdr l) next? keys (cons (part-collect-decl-element (car l)) colls) accum title tag-prefix tags style)]
+       [(part-tag-decl? (car l))
+        (loop (cdr l) next? keys colls accum title tag-prefix (cons (part-tag-decl-tag (car l)) tags) style)]
        [(and (pair? (cdr l))
 	     (splice? (cadr l)))
 	(loop (cons (car l) (append (splice-run (cadr l)) (cddr l))) next? keys colls accum title tag-prefix tags style)]
diff --git a/collects/scribble/doc/lang/reader.ss b/collects/scribble/doc/lang/reader.ss
index fbe0d072..fa4f99f8 100644
--- a/collects/scribble/doc/lang/reader.ss
+++ b/collects/scribble/doc/lang/reader.ss
@@ -1,4 +1,4 @@
 (module reader mzscheme
-  (require (prefix doc: (lib "docreader.ss" "scribble")))
+  (require (prefix doc: (lib "reader.ss" "scribble" "doc")))
   (provide (rename doc:read read)
            (rename doc:read-syntax read-syntax)))
diff --git a/collects/scribble/doc/main.ss b/collects/scribble/doc/main.ss
new file mode 100644
index 00000000..6dd33c88
--- /dev/null
+++ b/collects/scribble/doc/main.ss
@@ -0,0 +1,6 @@
+(module main scheme/base
+  (define-syntax-rule (out)
+    (begin (require scribble/doclang)
+           (provide (all-from-out scribble/doclang))))
+  (out))
+
diff --git a/collects/scribble/docreader.ss b/collects/scribble/doc/reader.ss
similarity index 89%
rename from collects/scribble/docreader.ss
rename to collects/scribble/doc/reader.ss
index b9e6ea8b..72cb2943 100644
--- a/collects/scribble/docreader.ss
+++ b/collects/scribble/doc/reader.ss
@@ -1,6 +1,6 @@
 
-(module docreader scheme/base
-  (require (prefix-in scribble: "reader.ss"))
+(module reader scheme/base
+  (require (prefix-in scribble: "../reader.ss"))
 
   (provide (rename-out [*read read])
            (rename-out [*read-syntax read-syntax]))
diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss
index 6fed3162..f84b3fa6 100644
--- a/collects/scribble/latex-render.ss
+++ b/collects/scribble/latex-render.ss
@@ -50,6 +50,7 @@
         (define-color "schemesymbol" "IdentifierColor")
         (define-color "schemevalue" "ValueColor")
         (define-color "schemevaluelink" "blue")
+        (define-color "schememodlink" "blue")
         (define-color "schemeresult" "ResultColor")
         (define-color "schemestdout" "OutputColor")
         (define-color "schememeta" "IdentifierColor")
diff --git a/collects/scribble/manual-struct.ss b/collects/scribble/manual-struct.ss
index eea0b8a8..11c0224e 100644
--- a/collects/scribble/manual-struct.ss
+++ b/collects/scribble/manual-struct.ss
@@ -4,6 +4,7 @@
          scheme/contract)
 
 (provide-structs
+ [module-path-index-desc ()]
  [exported-index-desc ([name symbol?]
                         [from-libs (listof module-path?)])]
  [(method-index-desc exported-index-desc) ([method-name symbol?]
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
index e9e54c41..0359209c 100644
--- a/collects/scribble/manual.ss
+++ b/collects/scribble/manual.ss
@@ -47,8 +47,11 @@
                               #'here
                               `(unsyntax (make-element
                                           #f
-                                          (list (schemefont ,(format "#lang "))
-                                                (schemeidfont ,(format "~s" (syntax-e #'lang))))))
+                                          (list hash-lang
+                                                (hspace 1)
+                                                (as-modname-link
+                                                 ',#'lang
+                                                 (to-element ',#'lang)))))
                               #'lang)])
          #'(schemeblock modtag rest ...))]))
 
@@ -83,7 +86,76 @@
   (define-code scheme to-element unsyntax keep-s-expr add-sq-prop)
   (define-code schemeresult to-element/result unsyntax keep-s-expr add-sq-prop)
   (define-code schemeid to-element/id unsyntax keep-s-expr add-sq-prop)
-  (define-code schememodname to-element unsyntax keep-s-expr add-sq-prop)
+  (define-code *schememodname to-element unsyntax keep-s-expr add-sq-prop)
+
+  (define-syntax-rule (schememodname n)
+    (as-modname-link 'n (*schememodname n)))
+
+  (define (as-modname-link s e)
+    (if (symbol? s)
+        (make-link-element "schememodlink"
+                           (list e)
+                           `(mod-path ,(symbol->string s)))
+        e))
+
+  (define-syntax-rule (defmodule*/no-declare (name ...) . content)
+    (*defmodule (list (schememodname name) ...)
+                #f
+                (list . content)))
+
+  (define-syntax-rule (defmodule* (name ...) . content)
+    (begin
+      (declare-exporting name ...)
+      (defmodule*/no-declare (name ...) . content)))
+
+  (define-syntax-rule (defmodule name . content)
+    (defmodule* (name) . content))
+  
+  (define-syntax-rule (defmodulelang*/no-declare (lang ...) . content)
+    (*defmodule (list (schememodname lang) ...)
+                #t
+                (list . content)))
+
+  (define-syntax-rule (defmodulelang* (name ...) . content)
+    (begin
+      (declare-exporting name ...)
+      (defmodulelang*/no-declare (name ...) . content)))
+
+  (define-syntax-rule (defmodulelang lang . content)
+    (defmodulelang* (lang) . content))
+
+  (define (*defmodule names lang? content)
+    (make-splice
+     (cons
+      (make-table
+       "defmodule"
+       (map (lambda (name)
+              (list
+               (make-flow
+                (list (make-paragraph
+                       (if lang?
+                           (list (hspace 1)
+                                 hash-lang
+                                 (hspace 1)
+                                 (make-defschememodname name))
+                           (list
+                            (hspace 1)
+                            (scheme (require #,(make-defschememodname name))))))))))
+            names))
+      (append
+       (map (lambda (name)
+              (make-part-tag-decl `(mod-path ,(element->string name))))
+            names)
+       (flow-paragraphs (decode-flow content))))))
+  
+  (define (make-defschememodname mn)
+    (let ([name-str (element->string mn)])
+      (make-index-element #f
+                          (list mn)
+                          `(mod-path ,name-str)
+                          (list name-str)
+                          (list mn)
+                          (make-module-path-index-desc))))
 
   (define (litchar . strs)
     (unless (andmap string? strs)
@@ -148,6 +220,8 @@
            schemeinput
            schememod
            scheme scheme/form schemeresult schemeid schememodname
+           defmodule defmodule* defmodulelang defmodulelang*
+           defmodule*/no-declare defmodulelang*/no-declare
            indexed-scheme
            litchar
            verbatim)
@@ -1375,6 +1449,13 @@
              c)))
   (provide pidefterm)
 
+
+  (define hash-lang (make-link-element
+                     "schememodlink"
+                     (list (schememodfont "#lang"))
+                     `(part ,(doc-prefix '(lib "scribblings/guide/guide.scrbl")
+                                         "hash-lang"))))
+  
   ;; ----------------------------------------
 
   (provide math)
diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css
index 0604c3fe..2365f237 100644
--- a/collects/scribble/scribble.css
+++ b/collects/scribble/scribble.css
@@ -289,6 +289,11 @@
                background-color: #ddddff;
                }
 
+               .defmodule {
+                 width: 100%;
+                 background-color: #F5F5DC;
+               }
+
                .specgrammar {
                float: right;
                }
@@ -369,6 +374,11 @@
                color: blue;
                }
 
+               .schememodlink { 
+               text-decoration: none;
+               color: blue;
+               }
+
                .schemesyntaxlink { 
                text-decoration: none;
                color: black;
diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl
index baf5a0a8..57c1592e 100644
--- a/collects/scribblings/scribble/basic.scrbl
+++ b/collects/scribblings/scribble/basic.scrbl
@@ -21,12 +21,12 @@
 
 @title[#:tag "basic"]{Basic Document Forms}
 
-@declare-exporting[scribble/basic]
+@defmodule[scribble/basic]{The @schememodname[scribble/basic] libraryp
+rovides functions and forms that can be used from code written either
+in Scheme or with @elem["@"] expressions.}
 
-The @filepath{basic.ss} libraryprovides functions and forms that can be
-used from code written either in Scheme or with @elem["@"]
-expressions. For example, the @scheme[title] and @scheme[italic]
-functions might be called from Scheme as
+For example, the @scheme[title] and @scheme[italic] functions might be
+called from Scheme as
 
 @schemeblock[
 (title #:tag "how-to" "How to Design " (italic "Great") " Programs")
@@ -42,7 +42,7 @@ EOS
 
 Although the procedures are mostly design to be used from @elem["@"]
 mode, they are easier to document in Scheme mode (partly because we
-have Scribble's @filepath{scheme.ss} and @filepath{manual.ss}).
+have @schememodname[scribble/manual]).
 
 @; ------------------------------------------------------------------------
 
diff --git a/collects/scribblings/scribble/bnf.scrbl b/collects/scribblings/scribble/bnf.scrbl
new file mode 100644
index 00000000..72cd5a80
--- /dev/null
+++ b/collects/scribblings/scribble/bnf.scrbl
@@ -0,0 +1,59 @@
+#lang scribble/doc
+@(require scribble/manual
+          "utils.ss"
+          (for-label scribble/bnf))
+
+@title[#:tag "bnf"]{Typesetting Grammars}
+
+@defmodule[scribble/bnf]{The @scheme[scribble/bnf] library
+provides utilities for typesetting grammars.}
+
+See also @scheme[schemegrammar].
+
+@defproc[(BNF [prod (cons element? (listof element?))] ...) table?]{
+
+Typesets a grammar table. Each production starts with an element
+(typically constructed with @scheme[nonterm]) for the non-terminal
+being defined, and then a list of possibilities (typically constructed
+with @scheme[BNF-seq], etc.) to show on separate lines.}
+
+@defproc[(nonterm (pre-content any/c) ...) element?]{
+
+Typesets a non-terminal: italic in angle brackets.}
+
+@defproc[(BNF-seq [elem element?] ...) element?]{
+
+Typesets a sequence.}
+
+@defproc[(BNF-group [pre-content any/c] ...) element?]{
+
+Typesets a group surrounded by curly braces (so the entire group can
+be repeated, for example).}
+
+@defproc[(optional [pre-content any/c] ...) element?]{
+
+Typesets an optional element: in square brackets.}
+
+@defproc[(kleenestar [pre-content any/c] ...) element?]{
+
+Typesets a 0-or-more repetition.}
+
+@defproc[(kleeneplus [pre-content any/c] ...) element?]{
+
+Typesets a 1-or-more repetition.}
+
+@defproc[(kleenerange [n any/c] [m any/c] [pre-content any/c] ...) element?]{
+
+Typesets a @scheme[n]-to-@scheme[m] repetition. The @scheme[n] and
+@scheme[m] arguments are converted to a string using @scheme[(format
+"~a" n)] and @scheme[(format "~a" m)].}
+
+@defproc[(BNF-alt [elem element?] ...) element?]{
+
+Typesets alternatives for a production's right-hand side to appear on
+a single line. The result is normally used as a single possibility in
+a production list for @scheme[BNF].}
+
+@defthing[BNF-etc string?]{
+
+A string to use for omitted productions or content.}
diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl
index 92b2ad25..2bc88545 100644
--- a/collects/scribblings/scribble/decode.scrbl
+++ b/collects/scribblings/scribble/decode.scrbl
@@ -4,12 +4,11 @@
 
 @title[#:tag "decode"]{Text Decoder}
 
-@declare-exporting[scribble/decode]
-
-The @filepath{decode.ss} library helps you write document content in a
-natural way---more like plain text, except for @litchar["@"] escapes.
-Roughly, it processes a stream of strings to produces instances of the
-@filepath{struct.ss} datatypes (see @secref["struct"]).
+@defmodule[scribble/decode]{The @schememodname[scribble/decode]
+library helps you write document content in a natural way---more like
+plain text, except for @litchar["@"] escapes.  Roughly, it processes a
+stream of strings to produces instances of the
+@schememodname[scribble/struct] datatypes (see @secref["struct"]).}
 
 At the flow level, decoding recognizes a blank line as a paragraph
 separator. At the paragraph-content level, decoding makes just a few
@@ -39,9 +38,10 @@ Decodes a document, producing a part. In @scheme[lst], instances of
 @scheme[part-index-decl] (that precede any sub-part) add index entries
 that point to the section. Instances of @scheme[part-collect-decl] add
 elements to the part that are used only during the @techlink{collect
-pass}. Instances of @scheme[part-start] at level 0 trigger sub-part
-parsing. Instances of @scheme[section] trigger are used as-is as
-subsections, and instances of @scheme[paragraph] and other
+pass}. Instances of @scheme[part-tag-decl] add hyperlink tags to the
+section title. Instances of @scheme[part-start] at level 0 trigger
+sub-part parsing. Instances of @scheme[section] trigger are used as-is
+as subsections, and instances of @scheme[paragraph] and other
 flow-element datatypes are used as-is in the enclosing flow.
 
 }
@@ -129,6 +129,12 @@ See @scheme[decode].
 
 }
 
+@defstruct[part-tag-decl ([tag tag?])]{
+
+See @scheme[decode].
+
+}
+
 @defstruct[splice ([run list?])]{
 
 See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow].
diff --git a/collects/scribblings/scribble/doclang.scrbl b/collects/scribblings/scribble/doclang.scrbl
index 44bd1f3f..f2ebb8fe 100644
--- a/collects/scribblings/scribble/doclang.scrbl
+++ b/collects/scribblings/scribble/doclang.scrbl
@@ -4,13 +4,14 @@
 
 @title[#:tag "doclang"]{Document Module Language}
 
-The @filepath{doclang.ss} module is suitable for use as a module
-language. It provides everything from @scheme[mzscheme], except that
-it replaces the @scheme[#%module-begin] form.
+@defmodule[scribble/doclang]{The @schememodname[scribble/doclang]
+language provides everything from @scheme[scheme/base], except that it
+replaces the @scheme[#%module-begin] form.}
 
-The @filepath{doclang.ss} @scheme[#%module-begin] essentially packages the
-body of the module into a call to @scheme[decode], binds the result to
-@scheme[doc], and exports @scheme[doc].
+The @schememodname[scribble/doclang] @scheme[#%module-begin]
+essentially packages the body of the module into a call to
+@scheme[decode], binds the result to @scheme[doc], and exports
+@scheme[doc].
 
 Any module-level form other than an expression (e.g., a
 @scheme[require] or @scheme[define]) is remains at the top level, and
diff --git a/collects/scribblings/scribble/docreader.scrbl b/collects/scribblings/scribble/docreader.scrbl
index 24a92d9c..ebfc4899 100644
--- a/collects/scribblings/scribble/docreader.scrbl
+++ b/collects/scribblings/scribble/docreader.scrbl
@@ -5,9 +5,8 @@
 
 @title[#:tag "docreader"]{Document Reader}
 
-The @filepath{docreader.ss} module is suitable for use with
-@schemefont{#reader} at the beginning of a file. It reads the entire
-file with @scheme[read-inside-syntax] from Scribble's
-@filepath{reader.ss}, and then wraps the result with @scheme[(module #,
-@nonterm{name} (lib "doclang.ss" "scribble") ...)], where
-@nonterm{name} is derived from the enclosing file's name.
+@defmodule[scribble/doc]{The @schememodname[scribble/doc] language is
+the same as @schememodname[scribble/doclang], except that
+@scheme[read-inside-syntax] is used to read the body of the module. In
+other words, the module body starts in Scribble ``text'' mode instead
+of S-expression mode.}
diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl
index eca3216c..2592e4e8 100644
--- a/collects/scribblings/scribble/eval.scrbl
+++ b/collects/scribblings/scribble/eval.scrbl
@@ -4,11 +4,10 @@
 
 @title[#:tag "eval"]{Evaluation and Examples}
 
-@declare-exporting[scribble/eval]
-
-The @filepath{eval.ss} library provides utilities for evaluating code at
-document-build time and incorporating the results in the document,
-especially to show example uses of defined procedures and syntax.
+@defmodule[scribble/eval]{The @scheme[scribble/eval] library provides
+utilities for evaluating code at document-build time and incorporating
+the results in the document, especially to show example uses of
+defined procedures and syntax.}
 
 @defform[(interaction datum ...)]{Like @scheme[schemeinput], except
 that the result for each input @scheme[datum] is shown on the next
diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl
index 570d913b..4bec9e8e 100644
--- a/collects/scribblings/scribble/how-to.scrbl
+++ b/collects/scribblings/scribble/how-to.scrbl
@@ -19,7 +19,7 @@ To document a collection or @|PLaneT| package:
  @item{Start @filepath{manual.scrbl} like this:
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual)]
+  @(require scribble/manual)
 
   @title{My Library}
 
@@ -52,8 +52,14 @@ EOS
         collection name to limit the build process to the collection.}
 
   @item{The generated documentation is
-        @filepath{compiled/doc/manual/index.html} within the collection or
-        @|PLaneT| package directory.}
+        @filepath{compiled/doc/manual/index.html} within the
+        collection or @|PLaneT| package directory.
+
+        If you want the output to be relative to the PLT Scheme
+        documentation directory (which is recommend only for those who
+        produce the ``official'' PLT Scheme distribution), add the
+        @scheme['main-doc] option to the @scheme[scribblings]
+        definition in @filepath{info.ss}.}
 
 }
 
@@ -88,13 +94,20 @@ A @nonterm{cmd} or @nonterm{datum} is a Scheme datum, while a
 
 The expansion of a @litchar["@"] form into Scheme code is
 
+@schemeblock[
+  @nonterm{cmd}
+]
+
+if neither @litchar["["] @litchar["]"] nor @litchar["{"] @litchar["}"]
+are used, otherwise
+
 @schemeblock[
   (#, @nonterm{cmd} #, @kleenestar{@nonterm{datum}} #, @kleenestar{@nonterm{parsed-body}})
 ]
 
 where @kleenestar{@nonterm{parsed-body}} is the parse result of the
-@nonterm{text-body}. It often turns out to be a sequence of Scheme
-strings.
+@nonterm{text-body}. The @kleenestar{@nonterm{parsed-body}} part often
+turns out to be a sequence of Scheme strings.
 
 In practice, the @nonterm{cmd} is normally a Scheme identifier that is
 bound to a procedure or syntactic form. If the procedure or form
@@ -136,18 +149,20 @@ information on the decoding process.
 @; ----------------------------------------
 @section[#:tag "scheme-hyperlinks"]{Scheme Typesetting and Hyperlinks}
 
-With the document source in @secref["getting-started"], the Scheme
-expression @scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is
-typeset properly, but the @schemeidfont{list} identifier is not
-hyperlinked to the usual definition. To cause @schemeidfont{list} to
-be hyperlinked, add the following to the @tt["@begin"] body:
+In the document source at the start of this chapter
+(@secref["getting-started"]), the Scheme expression
+@scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is typeset properly,
+but the @schemeidfont{list} identifier is not hyperlinked to the usual
+definition. To cause @schemeidfont{list} to be hyperlinked, extend the
+@scheme[require] form like this:
 
 @schemeblock[
-(require (for-label (lib "scheme")))
+(require scribble/manual
+         (for-label #,(schememodname scheme)))
 ]
 
 This @scheme[require] with @scheme[for-label] declaration introduces a
-document-time binding for each export of the @scheme[(lib "scheme")]
+document-time binding for each export of the @schememodname[scheme]
 module. When the document is built, the @scheme[scheme] form detects
 the binding for @scheme[list], and so it generates a reference to the
 specification of @scheme[list]. The setup process detects the
@@ -162,8 +177,8 @@ binding is documented elsewhere:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme")))]
+  @(require scribble/manual
+            (for-label scheme))
 
   @title{My Library}
 
@@ -178,8 +193,8 @@ and it preserves the expression's formatting from the document source.
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme"))]
+  @(require scribble/manual
+            (for-label scheme))
 
   @title{My Library}
 
@@ -209,8 +224,8 @@ The following example illustrates section hyperlinks:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme")))]
+  @(require scribble/manual
+            (for-label scheme))
 
 
   @title{My Library}
@@ -231,9 +246,9 @@ The following example illustrates section hyperlinks:
 EOS
 ]
 
-Since the page is so short, it the hyperlinks are more effective if
- you change the @filepath{info.ss} file to add the @scheme['multi-file]
- flag:
+Since the page is so short, it the hyperlinks in the above example are
+ more effective if you change the @filepath{info.ss} file to add the
+ @scheme['multi-file] flag:
 
 @schemeblock[
 (define scribblings '(("manual.scrbl" (multi-page))))
@@ -249,10 +264,10 @@ manual:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme")))
-         (define ref-src
-           '(lib "scribblings/reference/reference.scrbl"))]
+  @(require scribble/manual
+            (for-label scheme))
+  @(define ref-src
+     '(lib "scribblings/reference/reference.scrbl"))]
 
   @title{My Library}
 
@@ -261,9 +276,9 @@ EOS
 ]
 
 As mentioned in @secref{scheme-hyperlinks}, however, cross-document
-references based on @scheme[require-for-label] and @scheme[scheme] are
-usually better than to cross-document references using
-@scheme[secref].
+references based on @scheme[(require (for-label ....))] and
+@scheme[scheme] are usually better than to cross-document references
+using @scheme[secref].
 
 @; ----------------------------------------
 @section{Defining Scheme Bindings}
@@ -275,16 +290,16 @@ and they declare hyperlink targets for @scheme[scheme]-based
 hyperlinks.
 
 To document a @scheme[my-helper] procedure that is exported by
-@filepath{helper.ss} in the collection that contains @filepath{manual.scrbl},
-first use @scheme[require-for-label] to import the binding information
-of @filepath{helper.ss}. Then use @scheme[defproc] to document the
-procedure:
+@filepath{helper.ss} in the collection that contains
+@filepath{manual.scrbl}, first use @scheme[(require (for-label ....))]
+to import the binding information of @filepath{helper.ss}. Then use
+@scheme[defproc] to document the procedure:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme")
-                             "helper.ss"))]
+  @(require scribble/manual
+            (for-label scheme
+                       "helper.ss"))
 
   @title{My Library}
 
@@ -305,6 +320,30 @@ of the result must be given; in this case, @scheme[my-helper]
 guarantees a result that is a list where none of the elements are
 @scheme['cow].
 
+Finally, the documentation should declare the module that is being
+defined. Use @scheme[defmodule] to declare the module name before any
+other definitions.
+
+@verbatim[#<<EOS
+  #lang scribble/doc
+  @(require scribble/manual
+            (for-label scheme
+                       "helper.ss"))
+
+  @title{My Library}
+
+  @defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
+  module---now with extra cows!}
+
+  @defproc[(my-helper [lst list?])
+           (listof 
+            (not/c (one-of/c 'cow)))]{
+
+   Replaces each @scheme['cow] in @scheme[lst] with
+   @scheme['aardvark].}
+EOS
+]
+
 Some things to notice in this example and the documentation that it
 generates:
 
@@ -324,9 +363,12 @@ generates:
        it's used in the scope of a procedure with argument
        @scheme[_lst].}
 
+ @item{If you hover the mouse pointer over @scheme[my-helper], a popup
+       reports that it is provided from @schemeidfont{my-lib/helper}.}
+
  @item{If you use @scheme[my-helper] in any documentation now, as long
-       as that documentation source also has a
-       @scheme[require-for-label] of @filepath{my-helper.ss}, then the
+       as that documentation source also has a @scheme[(require
+       (for-label ....))] of @filepath{my-helper.ss}, then the
        reference is hyperlinked to the definition above.}
 
 }
@@ -350,14 +392,17 @@ via @scheme[require-for-label] and @scheme[require]:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  scribble/eval    ; <--- added
-                  "helper.ss"                 ; <--- added
-                  (for-label (lib "scheme")
-                             "helper.ss"))]
+  @(require scribble/manual
+            scribble/eval    ; <--- added
+            "helper.ss"      ; <--- added
+            (for-label scheme
+                       "helper.ss"))]
 
   @title{My Library}
 
+  @defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
+  module---now with extra cows!}
+
   @defproc[(my-helper [lst list?])
            (listof (not/c (one-of/c 'cow)))]{
 
@@ -384,10 +429,13 @@ In @filepath{manual.scrbl}:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual)]
+  @(require scribble/manual)
 
   @title{My Library}
 
+  @defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
+  module---now with extra cows!}
+
   @include-section["cows.scrbl"]
   @include-section["aardvarks.scrbl"]
 EOS
@@ -397,7 +445,7 @@ In @filepath{cows.scrbl}:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual)]
+  @(require scribble/manual)
 
   @title{Cows}
 
@@ -409,9 +457,9 @@ In @filepath{aardvarks.scrbl}:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual
-                  (for-label (lib "scheme")
-                             "helper.ss"))]
+  @(require scribble/manual
+            (for-label scheme
+                       "helper.ss"))
 
   @title{Aardvarks}
 
@@ -423,7 +471,6 @@ In @filepath{aardvarks.scrbl}:
 EOS
 ]
 
-
 @;----------------------------------------
 @section{Multi-Page Sections}
 
@@ -441,7 +488,7 @@ Revising @filepath{cows.scrbl} from the previous section:
 
 @verbatim[#<<EOS
   #lang scribble/doc
-  @begin[(require scribble/manual)]
+  @(require scribble/manual)
 
   @title[#:style '(toc)]{Cows}
 
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
index cf3db754..3c8138db 100644
--- a/collects/scribblings/scribble/manual.scrbl
+++ b/collects/scribblings/scribble/manual.scrbl
@@ -5,10 +5,10 @@
 
 @title[#:tag "manual"]{PLT Manual Forms}
 
-@declare-exporting[scribble/manual]
-
-The @filepath{manual.ss} module provides all of @filepath{basic.ss}, and
-more...
+@defmodule[scribble/manual]{The @schememodname[scribble/manual]
+provides all of @schememodname[scribble/basic], plus additional
+functions that are relatively specific to writing PLT Scheme
+documentation.}
 
 @; ------------------------------------------------------------------------
 @section[#:tag "scribble:manual:code"]{Typesetting Code}
@@ -102,7 +102,7 @@ without insetting the code.}
 @scheme[datum] are typeset after a prompt representing a REPL.}
 
 @defform[(schememod lang datum ...)]{Like @scheme[schemeblock], but
-the @scheme[datum] are typeset inside a @schemefont{#module}-form
+the @scheme[datum] are typeset inside a @schememodfont{#lang}-form
 module whose language is @scheme[lang].}
 
 @defform[(scheme datum ...)]{Like @scheme[schemeblock], but typeset on
@@ -115,8 +115,10 @@ as a REPL value (i.e., a single color with no hyperlinks).}
 @defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset
 as an unbound identifier (i.e., no coloring or hyperlinks).}
 
-@defform[(schememodname datum ...)]{Like @scheme[scheme], but typeset
-as a @schemefont{#module} language name.}
+@defform[(schememodname datum)]{Like @scheme[scheme], but typeset as a
+module path. If @scheme[datum] is an identifier, then it is
+hyperlinked to the module path's definition as created by
+@scheme[defmodule].}
 
 @defproc[(litchar [str string?]) element?]{Typesets @scheme[str] as a
 representation of literal text. Use this when you have to talk about
@@ -130,7 +132,7 @@ useful with @scheme[verbatim].}
 
 @defproc[(schemefont [pre-content any/c] ...) element?]{Typesets the given
 content as uncolored, unhyperlinked Scheme. This procedure is useful
-for typesetting things like @scheme{#module}, which are not
+for typesetting things like @schemefont{#lang}, which are not
 @scheme[read]able by themselves.}
 
 @defproc[(schemevalfont [pre-content any/c] ...) element?]{Like
@@ -167,7 +169,65 @@ cannot work for some reason.}
 in a form definition.}
 
 @; ------------------------------------------------------------------------
-@section{Definition Reference}
+@section{Documenting Modules}
+
+@defform[(defmodule id pre-flow ...)]{
+
+Produces a sequence of flow elements (encaptured in a @scheme[splice])
+to start the documentation for a module that can be @scheme[require]d
+using the path @scheme[id]. The @scheme[pre-flow]s list is parsed as a
+flow that documents the procedure (see @scheme[decode-flow]).
+
+Besides generating text, this form expands to a use of
+@scheme[declare-exporting] with @scheme[id].
+
+Hyperlinks created by @scheme[schememodname] are associated with the
+enclosing section, rather than the local @scheme[id] text.}
+
+
+@defform[(defmodulelang id pre-flow ...)]{
+
+Like @scheme[defmodule], but documents @scheme[id] as a module path
+suitable for use by either @scheme[require] or @schememodfont{#lang}.}
+
+
+@defform[(defmodule* (id ...) pre-flow ...)]{
+
+Like @scheme[defmodule], but introduces multiple module paths instead
+of just one.}
+
+
+@defform[(defmodulelang* (id ...) pre-flow ...)]{
+
+Like @scheme[defmodulelang], but introduces multiple module paths
+instead of just one.}
+
+
+@defform[(defmodule*/no-declare (id ...) pre-flow ...)]{
+
+Like @scheme[defmodule*], but without expanding to
+@scheme[declare-exporting]. Use this form when you want to provide a
+more specific list of modules (e.g., to name both a specific module
+and one that combines several modules) via your own
+@scheme[declare-exporting] declaration.}
+
+
+@defform[(defmodulelang*/no-declare (id ...) pre-flow ...)]{
+
+Like @scheme[defmodulelang*], but without expanding to
+@scheme[declare-exporting].}
+
+
+@defform[(declare-exporting module-path ...)]{
+
+Associates the @scheme[module-paths]s to all bindings defined within
+the enclosing section, except as overridden by other
+@scheme[declare-exporting] declarations in nested sub-sections.  The
+list of @scheme[module-path]s is shown, for example, when the user
+hovers the mouse over one of the bindings defined within the section.}
+
+@; ------------------------------------------------------------------------
+@section{Documenting Forms, Functions, Structure Types, and Values}
 
 @defform/subs[(defproc (id arg-spec ...)
                        result-contract-expr-datum
@@ -378,7 +438,7 @@ Like @scheme[schemegrammar], but for typesetting multiple productions
 at once, aligned around the @litchar{=} and @litchar{|}.}
 
 @; ------------------------------------------------------------------------
-@section{Classes and Interfaces}
+@section{Documenting Classes and Interfaces}
 
 @defform[(defclass id super-id (intf-id ...) pre-flow ...)]{
 
diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl
index 609b6c56..d9290c10 100644
--- a/collects/scribblings/scribble/reader.scrbl
+++ b/collects/scribblings/scribble/reader.scrbl
@@ -23,9 +23,7 @@ meaning of these S-expressions depends on the rest of your own code.
 
 A PLT Scheme manual more likely starts with
 
-@schemeblock[
- #, @schemefont{#lang scribble/doc}
-]
+@schememod[scribble/doc]
 
 which installs a reader, wraps the file content afterward into a
 MzScheme module, and parses the body into a document using
@@ -35,7 +33,7 @@ Another way to use the reader is to use the @scheme[use-at-readtable]
 function to switch the current readtable to a readtable that parses
 @"@"-forms.  You can do this in a single command line:
 
-@commandline{mzscheme -Le reader.ss scribble "(use-at-readtable)"}
+@commandline{mzscheme -l scheme -l scribble/reader -e "(use-at-readtable)"}
 
 @;--------------------------------------------------------------------
 @section{Concrete Syntax}
@@ -721,9 +719,8 @@ an example of this.
 @;--------------------------------------------------------------------
 @section{Interface}
 
-@declare-exporting[scribble/reader]
-
-The @filepath{reader.ss} module provides functionality for advanced needs.
+@defmodule[scribble/reader]{The @schememodname[scribble/reader] module
+provides direct Scribble reader functionality for advanced needs.}
 
 @; The `with-scribble-read' trick below shadows `read' and
 @;  `read-syntax' with for-label bindings from the Scribble reader
diff --git a/collects/scribblings/scribble/renderer.scrbl b/collects/scribblings/scribble/renderer.scrbl
index 30a8d6b6..7f833b73 100644
--- a/collects/scribblings/scribble/renderer.scrbl
+++ b/collects/scribblings/scribble/renderer.scrbl
@@ -13,23 +13,36 @@ tends to be format-independent, and it usually implemented completely
 by the base renderer. The latter method generates the actual output,
 which is naturally specific to a particular format.
 
-The @filepath{base-render.ss} module provides @scheme[render%], which
-implements the core of a renderer. The @filepath{html-renderer.ss},
-@filepath{latex-renderer.ss}, and @filepath{text-renderer.ss} modules each
-provide @scheme[renderer-mixin] to extend the base. The
-@filepath{html-renderer.ss} module also provides
-@scheme[multi-renderer-mixin] to produce multi-file HTML instead
-instead of single-file HTML.
+@defmodule[scribble/base-render]{The
+@schememodname[scribble/base-render] module provides @scheme[render%],
+which implements the core of a renderer.}
+
+@defmodule*/no-declare[(scribble/text-render)]{The
+@schememodname[scribble/text-render] module provides
+@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
+generating plain text.}
+
+@defmodule*/no-declare[(scribble/html-render)]{The
+@schememodname[scribble/html-render] module provides
+@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
+generating a single HTML file. It also supplies
+@schemeidfont{multi-renderer-mixin}, which further specializes the
+renderer to produce multi-file HTML.}
+
+@defmodule*/no-declare[(scribble/latex-render)]{The
+@schememodname[scribble/latex-render] module provides
+@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
+generating Latex.}
 
 The mixin structure is meant to support document-specific extensions
 to the renderers. For example, the @exec{scribble} command-line tool
 might, in the future, extract rendering mixins from a document module
 (in addition to the document proper).
 
-See @filepath{base-render.ss} for more information about the methods of
-the renderer. Documents built with higher layers, such as
-@filepath{manual.ss}, generally do not call the render object's methods
-directly.
+See the @filepath{base-render.ss} source for more information about
+the methods of the renderer. Documents built with higher layers, such
+as @schememodname[scribble/manual], generally do not call the render
+object's methods directly.
 
 @defclass[render% object% ()]{
 
diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl
new file mode 100644
index 00000000..7da38229
--- /dev/null
+++ b/collects/scribblings/scribble/scheme.scrbl
@@ -0,0 +1,12 @@
+#lang scribble/doc
+@require[scribble/manual]
+@require["utils.ss"]
+
+@title[#:tag "scheme"]{Scheme}
+
+@defmodule[scribble/scheme]{The @scheme[scribble/scheme] library
+provides utilities for typesetting Scheme code. The
+@scheme[scribble/manual] forms provide a higher-level interface.}
+
+@italic{To do:} document this library!
+
diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
index aa46fdcf..9e468222 100644
--- a/collects/scribblings/scribble/scribble.scrbl
+++ b/collects/scribblings/scribble/scribble.scrbl
@@ -26,52 +26,51 @@ The layers are:
 
 @itemize{
 
- @item{@filepath{reader.ss}: a reader that extends the syntax of Scheme
-       with @"@"-forms for conveniently embedding a mixin of text and
-       escapes. See @secref["reader"].}
+ @item{@schememodname[scribble/reader]: a reader that extends the
+       syntax of Scheme with @"@"-forms for conveniently embedding a
+       mixin of text and escapes. See @secref["reader"].}
 
- @item{@filepath{struct.ss}: a set of document datatypes and utilities
+ @item{@schememodname[scribble/struct]: a set of document datatypes and utilities
        that define the basic layout and processing of a document. See
        @secref["struct"].}
 
- @item{@filepath{base-render.ss} with @filepath{html-render.ss},
-       @filepath{latex-render.ss}, or @filepath{text-render.ss}: A base
+ @item{@schememodname[scribble/base-render] with @schememodname[scribble/html-render],
+       @schememodname[scribble/latex-render], or @schememodname[scribble/text-render]: A base
        renderer and mixins that generate documents in various formats
-       from instances of the @filepath{struct.ss} datatypes. See
+       from instances of the @schememodname[scribble/struct] datatypes. See
        @secref["renderer"].}
 
- @item{@filepath{decode.ss}: Processes a stream of text, section-start
-       markers, etc. to produce instances of the @filepath{struct.ss}
+ @item{@schememodname[scribble/decode]: Processes a stream of text, section-start
+       markers, etc. to produce instances of the @schememodname[scribble/struct]
        datatypes. See @secref["decode"].}
 
- @item{@filepath{doclang.ss}: to be used for the initial import of a
+ @item{@schememodname[scribble/doclang]: to be used for the initial import of a
        module; processes the module top level through
-       @filepath{decode.ss}, and otherwise provides all of
-       @schememodname[big].  See @secref["doclang"].}
+       @schememodname[scribble/decode], and otherwise provides all of
+       @schememodname[scheme/base].  See @secref["doclang"].}
 
- @item{@filepath{docreader.ss}: a reader that is meant to tbe used to
-       process an entire file; it essentially combines
-       @filepath{reader.ss} with @filepath{doclang.ss}. See
-       @secref["docreader"].}
+ @item{@schememodname[scribble/doc]: a language that essentially
+       combines @schememodname[scribble/reader] with
+       @schememodname[scribble/doclang]. See @secref["docreader"].}
 
- @item{@filepath{basic.ss}: a library of basic document operators---such
+ @item{@schememodname[scribble/basic]: a library of basic document operators---such
        as @scheme[title], @scheme[section], and @scheme[secref]---for
-       use with @filepath{decode.ss} and a renderer. See
+       use with @schememodname[scribble/decode] and a renderer. See
        @secref["basic"].}
 
- @item{@filepath{scheme.ss}: a library of support functions for
-       typesetting Scheme code.}
+ @item{@schememodname[scribble/scheme]: a library of support functions for
+       typesetting Scheme code. See @secref["scheme"].}
 
- @item{@filepath{manual.ss}: a library of support functions for writing
-       PLT Scheme documentation; re-exports @filepath{basic.ss}. See
+ @item{@schememodname[scribble/manual]: a library of support functions for writing
+       PLT Scheme documentation; re-exports @schememodname[scribble/basic]. See
        @secref["manual"].}
 
- @item{@filepath{eval.ss}: a library of support functions for ealuating
+ @item{@schememodname[scribble/eval]: a library of support functions for ealuating
        code at document-build time, especially for showing
        examples. See @secref["eval"].}
 
- @item{@filepath{bnf.ss}: a library of support functions for writing
-       grammars.}
+ @item{@schememodname[scribble/bnf]: a library of support functions for writing
+       grammars. See @secref["bnf"].}
 
 }
 
@@ -80,7 +79,7 @@ exports a @scheme{struct.ss}-based document, generating output with a
 specified renderer. More specifically, the executable installs a
 renderer, loads the specified modules and extracts the @scheme[doc]
 export of each (which must be an instance of @scheme[section] from
-@filepath{struct.ss}), and renders each. Use @exec{scribble -h} for more
+@schememodname[scribble/struct]), and renders each. Use @exec{scribble -h} for more
 information.
 
 @; ------------------------------------------------------------------------
@@ -91,7 +90,9 @@ information.
 @include-section["doclang.scrbl"]
 @include-section["docreader.scrbl"]
 @include-section["basic.scrbl"]
+@include-section["scheme.scrbl"]
 @include-section["manual.scrbl"]
 @include-section["eval.scrbl"]
+@include-section["bnf.scrbl"]
 
 @index-section[]
diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl
index 92c6b83c..e968e298 100644
--- a/collects/scribblings/scribble/struct.scrbl
+++ b/collects/scribblings/scribble/struct.scrbl
@@ -4,7 +4,7 @@
 
 @title[#:tag "struct"]{Document Structures And Processing}
 
-@declare-exporting[scribble/struct]
+@defmodule[scribble/struct]
 
 A document is represented as a @techlink{part}, as described in
  @secref["parts"]. This representation is intended to