From 19221251c7cc879ebe34789723319fd2967e2517 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 5 Jul 2011 07:01:50 -0600
Subject: [PATCH] scribble: clarify intent of `#:use-sources'

original commit: 5d06476cb3f91c7dbd370b1e24a5454cb4dd1229
---
 collects/scribblings/scribble/manual.scrbl | 59 +++++++++++++++++-----
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
index 6352c83f..e0ff7692 100644
--- a/collects/scribblings/scribble/manual.scrbl
+++ b/collects/scribblings/scribble/manual.scrbl
@@ -481,14 +481,15 @@ and one that combines several modules) via your own
 Associates the @racket[mod-path]s to all bindings defined within the
 enclosing section, except as overridden by other
 @racket[declare-exporting] declarations in nested sub-sections.  The
-list of @racket[mod-path]s is shown, for example, when the user hovers
-the mouse over one of the bindings defined within the section.
+list of @racket[mod-path]s before @racket[#:use-sources] is shown, for
+example, when the user hovers the mouse over one of the bindings
+defined within the section.
 
-More significantly, the first @racket[mod-path] plus the
-@racket[#:use-sources] @racket[mod-path]s determine the binding that
-is documented by each @racket[defform], @racket[defproc], or similar
-form within the section that contains the @racket[declare-exporting]
-declaration:
+More significantly, the first @racket[mod-path] before
+@racket[#:use-sources] plus the @racket[mod-path]s after
+@racket[#:use-sources] determine the binding that is documented by
+each @racket[defform], @racket[defproc], or similar form within the
+section that contains the @racket[declare-exporting] declaration:
 
 @itemize[
 
@@ -497,15 +498,47 @@ declaration:
        @racket[mod-path].}
 
  @item{If @racket[#:use-sources] @racket[mod-path]s are supplied, then
-       they are tried in order. The first one to provide an export
-       with the same symbolic name and
-       @racket[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 @racket[mod-path] in
-       the @racket[declare-exporting] declaration.}
+       they are tried in order before the first @racket[mod-path]. The
+       @racket[mod-path] that provides an export with the same
+       symbolic name and @racket[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
+       @racket[mod-path] in the @racket[declare-exporting]
+       declaration.}
 
 ]
 
+Use @racket[#:use-sources] sparingly, but it is needed when
+
+@itemlist[
+
+ @item{bindings are documented as originating from a module
+       @racket[_M], but the bindings are actually re-exported from
+       some module @racket[_P]; and}
+
+ @item{other documented modules also re-export the bindings from
+       @racket[_P], but they are documented as re-exporting from
+       @racket[_M].}
+
+]
+
+For example, the @racket[parameterize] binding of
+@racketmodname[mzscheme] is documented as re-exported from
+@racketmodname[racket/base], but @racket[parameterize] happens to be
+implemented in a private module and re-exported by both
+@racketmodname[racket/base] and @racketmodname[mzscheme].  Importing
+@racket[parameterize] from @racketmodname[mzscheme] does not go
+through @racketmodname[racket/base], so a search for documentation on
+@racket[parameterize] in @racketmodname[mzscheme] would not
+automatically connect to the documentation of
+@racketmodname[racket/base]. To make the connection, the documentation
+of @racketmodname[racket/base] declares the private module to be a
+source through @racket[#:use-sources], so that any re-export of
+@racket[parameterize] from the private module connects to the
+documentation for @racketmodname[racket/base] (unless a re-export has
+its own documentation, which would override the automatic connection
+when searching for documentation).
+
 The initial @racket[mod-path]s sequence can be empty if
 @racket[mod-path]s are given with @racket[#:use-sources]. In that
 case, the rendered documentation never reports an exporting module for