From 9097b87aca91b73515634c062d7403dcaccb2a3a Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 5 May 2013 10:19:41 -0600
Subject: [PATCH] make `scribble' (and `raco scribble') use a `doc' submodule
 when present

original commit: f60803c300e5c208d80b8e2567a2622f114758b5
---
 collects/scribble/run.rkt                   |  6 +++++-
 collects/scribblings/scribble/running.scrbl | 13 ++++++++++---
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/collects/scribble/run.rkt b/collects/scribble/run.rkt
index 7d116842..526ddb36 100644
--- a/collects/scribble/run.rkt
+++ b/collects/scribble/run.rkt
@@ -105,7 +105,11 @@
     (current-quiet #t)]
    #:args (file . another-file)
    (let ([files (cons file another-file)])
-     (build-docs (map (lambda (file) (dynamic-require `(file ,file) 'doc))
+     (build-docs (map (lambda (file) 
+                        ;; Try `doc' submodule, first:
+                        (if (module-declared? `(submod (file ,file) doc) #t)
+                            (dynamic-require `(submod (file ,file) doc) 'doc)
+                            (dynamic-require `(file ,file) 'doc)))
                       files)
                  files))))
 
diff --git a/collects/scribblings/scribble/running.scrbl b/collects/scribblings/scribble/running.scrbl
index 74e94a1f..c762370e 100644
--- a/collects/scribblings/scribble/running.scrbl
+++ b/collects/scribblings/scribble/running.scrbl
@@ -51,9 +51,16 @@ flag to specify a destination directory (for any number of source
 files). Use @DFlag{dest-base} to add a prefix to the name of each
 support file that is generated or copied to the destination.
 
-After all flags, provide one or more document sources. When multiple
-documents are rendered at the same time, cross-reference information
-in one document is visible to the other documents. See
+After all flags, provide one or more document sources, where each
+source declares a module. The module should either have a @racket[doc]
+@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{submodule}
+that exports @racket[doc] as a @racket[part], or it should directly
+export @racket[doc] as a @racket[part]. (The submodule is tried first,
+and the main module is not directly loaded or evaluated if the
+submodule can be loaded on its own.)
+
+When multiple documents are rendered at the same time, cross-reference
+information in one document is visible to the other documents. See
 @secref["xref-flags"] for information on references that cross
 documents that are built separately.