From 42daa454b88eebe63fb2f2ea4dcb245c6f27c965 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 14 Feb 2008 16:59:26 +0000
Subject: [PATCH] support documentation for bindings from a hypothetical
 module, as opposed to a specific module

svn: r8663

original commit: b87d9a986e99eaafc88789125153c0a1e39b5441
---
 collects/scribble/manual.ss                | 38 ++++++++++++++--------
 collects/scribblings/scribble/manual.scrbl | 29 +++++++++++++----
 2 files changed, 48 insertions(+), 19 deletions(-)

diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
index 1d898c2f..515bc141 100644
--- a/collects/scribble/manual.ss
+++ b/collects/scribble/manual.ss
@@ -256,13 +256,10 @@
   ;; String String *-> Element
   ;; an in-lined image, relative to the current directory 
   (define (image filename-relative-to-source . alt)
-    (centerline ;; this doesn't do anything? 
-      (make-element
-	(make-image-file filename-relative-to-source)
-	(decode-content alt))))
+    (make-element
+     (make-image-file filename-relative-to-source)
+     (decode-content alt)))
 
-  ;; MF! -- the centerline is used in the drscheme manual
-  ;; otherwise I'd switch 
   (define (image/plain filename-relative-to-source . alt)
     (make-element 
       (make-image-file filename-relative-to-source)
@@ -376,7 +373,8 @@
                                                              checker))))])
                           (and (checker id)
                                lib)))
-                      source-libs)
+                      (or source-libs
+                          null))
                (and (pair? libs)
                     (car libs)))])
       (and lib
@@ -571,10 +569,23 @@
            schemegrammar schemegrammar*
            var svar void-const undefined-const)
 
-  (define-syntax declare-exporting
-    (syntax-rules ()
-      [(_ lib ... #:use-sources (plib ...)) (*declare-exporting '(lib ...) '(plib ...))]
-      [(_ lib ...) (*declare-exporting '(lib ...) '())]))
+  (define-syntax (declare-exporting stx)
+    (syntax-case stx ()
+      [(_ lib ... #:use-sources (plib ...)) 
+       (let ([libs (syntax->list #'(lib ... plib ...))])
+         (for-each (lambda (l)
+                     (unless (module-path? (syntax->datum l))
+                       (raise-syntax-error #f
+                                           "not a module path"
+                                           stx
+                                           l)))
+                   libs)
+         (when (null? libs)
+           (raise-syntax-error #f
+                               "need at least one module path"
+                               stx))
+         #'(*declare-exporting '(lib ...) '(plib ...)))]
+      [(_ lib ...) #'(*declare-exporting '(lib ...) '())]))
 
   (define-struct (exporting-libraries element) (libs source-libs))
 
@@ -585,9 +596,10 @@
        (make-collect-element #f
                              null
                              (lambda (ri)
-                               (collect-put! ri '(exporting-libraries #f) libs))))
+                               (collect-put! ri '(exporting-libraries #f) 
+                                             libs))))
       (make-part-collect-decl
-       (make-exporting-libraries #f null libs source-libs)))))
+       (make-exporting-libraries #f null (and (pair? libs) libs) source-libs)))))
 
   (define-syntax (quote-syntax/loc stx)
     (syntax-case stx ()
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
index c2ae0970..d39ca489 100644
--- a/collects/scribblings/scribble/manual.scrbl
+++ b/collects/scribblings/scribble/manual.scrbl
@@ -209,13 +209,13 @@ Like @scheme[defmodule], but documents @scheme[id] as a module path
 suitable for use by either @scheme[require] or @schememodfont{#lang}.}
 
 
-@defform[(defmodule* (id ...) maybe-sources pre-flow ...)]{
+@defform[(defmodule* (id ...+) maybe-sources pre-flow ...)]{
 
 Like @scheme[defmodule], but introduces multiple module paths instead
 of just one.}
 
 
-@defform[(defmodulelang* (id ...) maybe-sources pre-flow ...)]{
+@defform[(defmodulelang* (id ...+) maybe-sources pre-flow ...)]{
 
 Like @scheme[defmodulelang], but introduces multiple module paths
 instead of just one.}
@@ -267,6 +267,13 @@ declaration:
 
 }
 
+The initial @scheme[mod-path]s sequence can be empty if
+@scheme[mod-path]s are given with @scheme[#:use-sources]. In that
+case, the rendered documentation never reports an exporting module for
+identifiers that are documented within the section, but the
+@scheme[mod-path]s in @scheme[#:use-sources] provide a binding context
+for connecting (via hyperlinks) definitions and uses of identifiers.
+
 The @scheme[declare-exporting] form should be used no more than once
 per section, since the declaration applies to the entire section,
 although overriding @scheme[declare-exporting] forms can appear in
@@ -862,12 +869,22 @@ combination of @scheme[envvar] and @scheme[as-index].}
 @; ------------------------------------------------------------------------
 @section{Images}
 
-@defproc[(image [filename-relative-to-source string?]) element?]{
- creates a centered image, from the given relative source path.}
+@defproc[(image [filename-relative-to-source string?]
+                [pre-element any/c] ...)
+         flow-element?]{
+ Creates a centered image from the given relative source path. The
+ @tech{decode}d @scheme[pre-content] serves as the alternate text for
+ contexts where the image cannot be displayed.
 
-@defproc[(image/plain [filename-relative-to-source string?]) element?]{
- creates an in-lined image, from the given relative source path.}
+ The path is relative to the current directory, which is set by
+ @exec{setup-plt} and @exec{scribble} to the directory of the main
+ document file.}
 
+@defproc[(image/plain [filename-relative-to-source string?]
+                      [pre-element any/c] ...)
+         element?]{
+ Like @scheme[image], but the result is an element to appear inline in
+ a paragraph.}
 
 @; ------------------------------------------------------------------------
 @section{Bibliography}