add #:use-sources to Scribble module declarations, so that scheme/base and mzscheme can better share documentation; finish documenting legacy mzscheme bindings

svn: r8538

original commit: 794e6c8a398da5857097795ff5c8d022bf55fed2

collects/scribble/manual.ss

@@ -108,10 +108,15 @@
                 #f
                 (list . content)))
 
-  (define-syntax-rule (defmodule* (name ...) . content)
+  (define-syntax defmodule*
-    (begin
+    (syntax-rules ()
-      (declare-exporting name ...)
+      [(_ (name ...) #:use-sources (pname ...) . content)
-      (defmodule*/no-declare (name ...) . content)))
+       (begin
+         (declare-exporting name ... #:use-sources (pname ...))
+         (defmodule*/no-declare (name ...) . content))]
+      [(_ (name ...) . content)
+       (defmodule* (name ...) #:use-sources () . content)]))
+      
 
   (define-syntax-rule (defmodule name . content)
     (defmodule* (name) . content))
@@ -121,10 +126,14 @@
                 #t
                 (list . content)))
 
-  (define-syntax-rule (defmodulelang* (name ...) . content)
+  (define-syntax defmodulelang* 
-    (begin
+    (syntax-rules ()
-      (declare-exporting name ...)
+      [(_ (name ...) #:use-sources (pname ...) . content)
-      (defmodulelang*/no-declare (name ...) . content)))
+       (begin
+         (declare-exporting name ... #:use-sources (pname ...))
+         (defmodulelang*/no-declare (name ...) . content))]
+      [(_ (name ...) . content)
+       (defmodulelang* (name ...) #:use-sources () . content)]))
 
   (define-syntax-rule (defmodulelang lang . content)
     (defmodulelang* (lang) . content))
@@ -338,14 +347,38 @@
           (annote-exporting-library
            (to-element (make-just-context name stx-id))))))
 
-  (define (libs->taglet libs)
+  (define checkers (make-hash-table 'equal))
-    (and (pair? libs)
+
-         (let ([p (resolved-module-path-name
+  (define (libs->taglet id libs source-libs)
-                   (module-path-index-resolve
+    (let ([lib 
-                    (module-path-index-join (car libs) #f)))])
+           (or (ormap (lambda (lib)
-           (if (path? p)
+                        (let ([checker (hash-table-get checkers lib
-               (intern-taglet (path->main-collects-relative p))
+                                                       (lambda ()
-               p))))
+                                                         (let ([ns (make-base-empty-namespace)])
+                                                           (parameterize ([current-namespace ns])
+                                                             (namespace-require `(for-label ,lib)))
+                                                           (let ([checker
+                                                                  (lambda (id)
+                                                                    (parameterize ([current-namespace ns])
+                                                                      (let ([new-id (namespace-syntax-introduce
+                                                                                     (datum->syntax
+                                                                                      #f
+                                                                                      (syntax-e id)))])
+                                                                        (free-label-identifier=? new-id id))))])
+                                                             (hash-table-put! checkers lib checker)
+                                                             checker))))])
+                          (and (checker id)
+                               lib)))
+                      source-libs)
+               (and (pair? libs)
+                    (car libs)))])
+      (and lib
+           (let ([p (resolved-module-path-name
+                     (module-path-index-resolve
+                      (module-path-index-join lib #f)))])
+             (if (path? p)
+                 (intern-taglet (path->main-collects-relative p))
+                 p)))))
 
   (define (id-to-target-maker id dep?)
     (*id-to-target-maker 'def id dep?))
@@ -373,7 +406,11 @@
                                      "no declared exporting libraries for definition"
                                      id)))
              (if e
-                 (let* ([lib-taglet (libs->taglet (exporting-libraries-libs e))]
+                 (let* ([lib-taglet (libs->taglet (if sig
+                                                      (sig-id sig)
+                                                      id)
+                                                  (exporting-libraries-libs e)
+                                                  (exporting-libraries-source-libs e))]
                         [tag (list (if sig
                                        (case sym
                                          [(def) 'sig-val]
@@ -529,11 +566,12 @@
 
   (define-syntax declare-exporting
     (syntax-rules ()
-      [(_ lib ...) (*declare-exporting '(lib ...))]))
+      [(_ lib ... #:use-sources (plib ...)) (*declare-exporting '(lib ...) '(plib ...))]
+      [(_ lib ...) (*declare-exporting '(lib ...) '())]))
 
-  (define-struct (exporting-libraries element) (libs))
+  (define-struct (exporting-libraries element) (libs source-libs))
 
-  (define (*declare-exporting libs)
+  (define (*declare-exporting libs source-libs)
     (make-splice
      (list
       (make-part-collect-decl
@@ -542,7 +580,7 @@
                              (lambda (ri)
                                (collect-put! ri '(exporting-libraries #f) libs))))
       (make-part-collect-decl
-       (make-exporting-libraries #f null libs)))))
+       (make-exporting-libraries #f null libs source-libs)))))
 
   (define-syntax (quote-syntax/loc stx)
     (syntax-case stx ()

collects/scribblings/scribble/manual.scrbl

@@ -184,7 +184,8 @@ in a form definition.}
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-modules"]{Documenting Modules}
 
-@defform[(defmodule id pre-flow ...)]{
+@defform/subs[(defmodule id maybe-sources pre-flow ...)
+              ([maybe-sources #:use-sources (mod-path ...)])]
 
 Produces a sequence of flow elements (encaptured in a @scheme[splice])
 to start the documentation for a module that can be @scheme[require]d
@@ -192,27 +193,29 @@ using the path @scheme[id]. The @tech{decode}d @scheme[pre-flow]s
 introduce the module, but need not include all of the module content.
 
 Besides generating text, this form expands to a use of
-@scheme[declare-exporting] with @scheme[id]. Consequently,
+@scheme[declare-exporting] with @scheme[id]; the
-@scheme[defmodule] should be used at most once in a section, though it
+@scheme[#:use-sources] clause, if provided, is propagated to
-can be shadowed with @scheme[defmodule]s in sub-sections.
+@scheme[declare-exporting]. Consequently, @scheme[defmodule] should be
+used at most once in a section, though it can be shadowed with
+@scheme[defmodule]s in sub-sections.
 
 Hyperlinks created by @scheme[schememodname] are associated with the
 enclosing section, rather than the local @scheme[id] text.}
 
 
-@defform[(defmodulelang id pre-flow ...)]{
+@defform[(defmodulelang id maybe-sources 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 ...)]{
+@defform[(defmodule* (id ...) maybe-sources pre-flow ...)]{
 
 Like @scheme[defmodule], but introduces multiple module paths instead
 of just one.}
 
 
-@defform[(defmodulelang* (id ...) pre-flow ...)]{
+@defform[(defmodulelang* (id ...) maybe-sources pre-flow ...)]{
 
 Like @scheme[defmodulelang], but introduces multiple module paths
 instead of just one.}
@@ -233,13 +236,36 @@ Like @scheme[defmodulelang*], but without expanding to
 @scheme[declare-exporting].}
 
 
-@defform[(declare-exporting module-path ...)]{
+@defform/subs[(declare-exporting mod-path ... maybe-sources)
+              ([maybe-sources #:use-sources (mod-path ...)])]{
                                  
-Associates the @scheme[module-paths]s to all bindings defined within
+Associates the @scheme[mod-path]s to all bindings defined within the
-the enclosing section, except as overridden by other
+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
+list of @scheme[mod-path]s is shown, for example, when the user hovers
-hovers the mouse over one of the bindings defined within the section.
+the mouse over one of the bindings defined within the section.
+
+More significantly, the first @scheme[mod-path] plus the
+@scheme[#:use-sources] @scheme[mod-path]s determine the binding that
+is documented by each @scheme[defform], @scheme[defproc], or similar
+form within the section that contains the @scheme[declare-exporting]
+declaration:
+
+@itemize{
+
+ @item{If no @scheme[#:use-sources] clause is supplied, then the
+       documentation applies to the given name as exported by the first
+       @scheme[mod-path].}
+
+ @item{If @scheme[#:use-sources] @scheme[mod-path]s are supplied, then
+       they are tried in order. The first one to provide an export
+       with the same symbolic name and
+       @scheme[free-label-identifier=?] to the given name is used as
+       the documented binding. This binding is assumed to be the same
+       as the identifier as exported by the first @scheme[mod-path] in
+       the @scheme[declare-exporting] declaration.}
+
+}
 
 The @scheme[declare-exporting] form should be used no more than once
 per section, since the declaration applies to the entire section,