add htdp/image, htdp/world defmodule to teachpack docs; minor Scribble extensions

svn: r13877

collects/scribble/private/manual-mod.ss

@@ -17,24 +17,37 @@
 
 (define spacer (hspace 1))
 
-(define-syntax-rule (defmodule*/no-declare (name ...) . content)
-  (*defmodule (list (schememodname name) ...)
-              #f
-              (list . content)))
+(define-syntax defmodule*/no-declare
+  (syntax-rules ()
+    [(_ #:require-form req (name ...) . content)
+     (*defmodule (list (schememodname name) ...)
+                 #f
+                 (list . content)
+                 req)]
+    [(_ (name ...) . content)
+     (defmodule*/no-declare #:require-form (scheme require) (name ...) . content)]))
 
 (define-syntax defmodule*
   (syntax-rules ()
-    [(_ (name ...) #:use-sources (pname ...) . content)
+    [(_ #:require-form req (name ...) #:use-sources (pname ...) . content)
      (begin (declare-exporting name ... #:use-sources (pname ...))
-            (defmodule*/no-declare (name ...) . content))]
+            (defmodule*/no-declare #:require-form req (name ...) . content))]
+    [(_ #:require-form req (name ...) . content)
+     (defmodule* #:require-form req (name ...) #:use-sources () . content)]
+    [(_ (name ...) #:use-sources (pname ...) . content)
+     (defmodule* #:require-form (scheme require) (name ...) #:use-sources (pname ...) . content)]
     [(_ (name ...) . content)
      (defmodule* (name ...) #:use-sources () . content)]))
 
-(define-syntax-rule (defmodule name . content)
-  (defmodule* (name) . content))
+(define-syntax defmodule
+  (syntax-rules ()
+    [(_ #:require-form req name . content)
+     (defmodule* #:require-form req (name) . content)]
+    [(_ name . content)
+     (defmodule* (name) . content)]))
 
 (define-syntax-rule (defmodulelang*/no-declare (lang ...) . content)
-  (*defmodule (list (schememodname lang) ...) #t (list . content)))
+  (*defmodule (list (schememodname lang) ...) #t (list . content) #f))
 
 (define-syntax defmodulelang*
   (syntax-rules ()
@@ -48,7 +61,7 @@
   (defmodulelang* (lang) . content))
 
 (define-syntax-rule (defmodulereader*/no-declare (lang ...) . content)
-  (*defmodule (list (schememodname lang) ...) 'reader (list . content)))
+  (*defmodule (list (schememodname lang) ...) 'reader (list . content) #f))
 
 (define-syntax defmodulereader*
   (syntax-rules ()
@@ -61,7 +74,7 @@
 (define-syntax-rule (defmodulereader lang . content)
   (defmodulereader* (lang) . content))
 
-(define (*defmodule names lang content)
+(define (*defmodule names lang content req)
   (make-splice
    (cons
     (make-table
@@ -78,7 +91,7 @@
                  (if (eq? lang 'reader)
                      (list (schememetafont "#reader") spacer (make-defschememodname name))
                      (list (hash-lang) spacer (make-defschememodname name)))
-                 (list (scheme (require #,(make-defschememodname name)))))))))))
+                 (list (scheme (#,req #,(make-defschememodname name)))))))))))
       names))
     (append (map (lambda (name)
                    (make-part-tag-decl `(mod-path ,(element->string name))))

collects/scribble/private/manual-scheme.ss

@@ -96,8 +96,13 @@
 (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-syntax-rule (schememodname n)
-  (as-modname-link 'n (*schememodname n)))
+(define-syntax schememodname
+  (syntax-rules (unsyntax)
+    [(schememodname #,n)
+     (let ([sym n])
+       (as-modname-link sym (to-element sym)))]
+    [(schememodname n)
+     (as-modname-link 'n (*schememodname n))]))
 
 (define (as-modname-link s e)
   (if (symbol? s)

collects/scribblings/scribble/manual.scrbl

@@ -141,8 +141,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
-module path. If @scheme[datum] is an identifier, then it is
+@defform*[((schememodname datum)
+           (schememodname ((unsyntax (scheme unsyntax)) expr)))]{
+Like @scheme[scheme], but typeset as a module path. If @scheme[datum]
+is an identifier or @scheme[expr] produces a symbol, then it is
 hyperlinked to the module path's definition as created by
 @scheme[defmodule].}
 
@@ -246,8 +248,10 @@ because the @"@"-reader would drop comments within the
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-modules"]{Documenting Modules}
 
-@defform/subs[(defmodule id maybe-sources pre-flow ...)
-              ([maybe-sources code:blank
+@defform/subs[(defmodule maybe-req id maybe-sources pre-flow ...)
+              ([maybe-req code:blank
+                          (code:line #:require-form expr)]
+               [maybe-sources code:blank
                               (code:line #:use-sources (mod-path ...))])]{
 
 Produces a sequence of flow elements (encaptured in a @scheme[splice])
@@ -262,6 +266,11 @@ Besides generating text, this form expands to a use of
 used at most once in a section, though it can be shadowed with
 @scheme[defmodule]s in sub-sections.
 
+If a @scheme[#:require-form] clause is provided, the given expression
+produces an element to use instead of @scheme[(scheme require)] for
+the declaration of the module. This is useful to suggest a different
+way of accessing the module instead of through @scheme[require].
+
 Hyperlinks created by @scheme[schememodname] are associated with the
 enclosing section, rather than the local @scheme[id] text.}
 
@@ -279,7 +288,7 @@ suitable for use with @schememetafont{#reader}.}
 
 
 @deftogether[(
-@defform[(defmodule* (id ...+) maybe-sources pre-flow ...)]
+@defform[(defmodule* maybe-req  (id ...+) maybe-sources pre-flow ...)]
 @defform[(defmodulelang* (id ...+) maybe-sources pre-flow ...)]
 @defform[(defmodulereader* (id ...+) maybe-sources pre-flow ...)]
 )]{
@@ -288,7 +297,7 @@ Like @scheme[defmodule], etc., but introduces multiple module paths instead
 of just one.}
 
 @deftogether[(
-@defform[(defmodule*/no-declare (id ...) pre-flow ...)]
+@defform[(defmodule*/no-declare maybe-req (id ...) pre-flow ...)]
 @defform[(defmodulelang*/no-declare (id ...) pre-flow ...)]
 @defform[(defmodulereader*/no-declare (id ...) pre-flow ...)]
 )]{

collects/teachpack/2htdp/scribblings/shared.ss

@@ -1,10 +1,5 @@
 #lang scheme/base
 
-(require scribble/manual)
+(require "../../htdp/scribblings/shared.ss")
 
-(provide teachpack)
-
-(define (teachpack tp . name)
-  (apply title #:tag tp
-         `(,@name ": " ,(filepath (format "~a.ss" tp))
-           ,(index (format "~a teachpack" tp)))))
+(provide teachpack beginner-require)

collects/teachpack/2htdp/scribblings/universe.scrbl

@@ -25,7 +25,7 @@
 
 @author{Matthias Felleisen}
 
-@defmodule[2htdp/universe #:use-sources (teachpack/htdp/image)]
+@defmodule[#:require-form beginner-require 2htdp/universe #:use-sources (teachpack/htdp/image)]
 
 @;{FIXME: the following paragraph uses `defterm' instead of `deftech',
    because the words "world" and "universe" are used as datatypes, and

collects/teachpack/htdp/scribblings/image.scrbl

@@ -7,8 +7,7 @@
 
 @teachpack["image"]{Manipulating Images}
 
-
-@declare-exporting[teachpack/htdp/image #:use-sources (htdp/image)]
+@defmodule[#:require-form beginner-require htdp/image]
 
 The teachpack provides primitives for constructing and manipulating
 images. Basic, colored images are created as outlines or solid

collects/teachpack/htdp/scribblings/shared.ss

@@ -2,9 +2,17 @@
 
 (require scribble/manual)
 
-(provide teachpack)
+(provide teachpack
+         beginner-require)
 
 (define (teachpack tp . name)
   (apply title #:tag tp
          `(,@name ": " ,(filepath (format "~a.ss" tp))
            ,(index (format "~a teachpack" tp)))))
+
+(define-syntax-rule (def-req beg-require)
+  (begin
+    (require (for-label lang/htdp-beginner))
+    (define beg-require (scheme require))))
+(def-req beginner-require)
+

collects/teachpack/htdp/scribblings/world.scrbl

@@ -10,6 +10,8 @@
 
 @teachpack["world"]{Simulations and Animations}
 
+@defmodule[#:require-form beginner-require htdp/world #:use-sources (htdp/image)]
+
 @emph{Note}: For a quick and educational introduction to the teachpack, see
 @link["http://www.ccs.neu.edu/home/matthias/HtDP/Prologue/book.html"]{How
 to Design Programs, Second Edition: Prologue}. As of August 2008, we also
@@ -26,8 +28,6 @@ The teachpack provides two sets of tools. The first allows students to
 create and display a series of animated scenes, i.e., a simulation. The
 second one generalizes the first by adding interactive GUI features. 
 
-@declare-exporting[teachpack/htdp/world #:use-sources (teachpack/htdp/image)]
-
 @; -----------------------------------------------------------------------------
 @section[#:tag "basics"]{Basics}