tighten some Scribble contracts, improve docs

svn: r8486

collects/scribble/base-render.ss

@@ -92,6 +92,11 @@
                        (collect-info-gen-prefix ci))
                    (collect-info-relatives ci)
                    (cons d (collect-info-parents ci)))])
+        (hash-table-put! (collect-info-parts ci)
+                         d
+                         (make-collected-info number
+                                              parent
+                                              (collect-info-ht p-ci)))
         (when (part-title-content d)
           (collect-content (part-title-content d) p-ci))
         (collect-part-tags d p-ci number)
@@ -106,11 +111,6 @@
                                   number))
               (loop (cdr parts)
                     (if (unnumbered-part? s) pos (add1 pos))))))
-        (hash-table-put! (collect-info-parts ci)
-                         d
-                         (make-collected-info number
-                                              parent
-                                              (collect-info-ht p-ci)))
         (let ([prefix (part-tag-prefix d)])
           (for ([(k v) (collect-info-ht p-ci)])
             (when (cadr k)

collects/scribble/struct.ss

@@ -77,13 +77,7 @@
 
   (provide 
    (struct-out collect-info)
-   (struct-out resolve-info)
+   (struct-out resolve-info))
-   part-collected-info
-   collect-put!
-   resolve-get
-   resolve-search
-   resolve-get/tentative
-   resolve-get-keys)
 
   ;; ----------------------------------------
 
@@ -489,5 +483,19 @@
 
   ;; ----------------------------------------
 
+  (define (info-key? l)
+    (and (pair? l)
+         (symbol? (car l))
+         (pair? (cdr l))))
+
+  (provide info-key?)
+  (provide/contract
+   [part-collected-info (part? resolve-info? . -> . collected-info?)]
+   [collect-put! (collect-info? info-key?  any/c . -> . any)]
+   [resolve-get ((or/c part? false/c) resolve-info? info-key? . -> . any)]
+   [resolve-get/tentative ((or/c part? false/c) resolve-info? info-key? . -> . any)]
+   [resolve-search (any/c (or/c part? false/c) resolve-info? info-key? . -> . any)]
+   [resolve-get-keys ((or/c part? false/c) resolve-info? (info-key? . -> . any/c) . -> . any/c)])
+
   )
 

collects/scribblings/scribble/manual.scrbl

@@ -192,7 +192,9 @@ 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].
+@scheme[declare-exporting] with @scheme[id]. 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.}
@@ -237,7 +239,12 @@ Associates the @scheme[module-paths]s to all bindings defined within
 the 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
-hovers the mouse over one of the bindings defined within the section.}
+hovers the mouse over one of the bindings defined within the section.
+
+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
+sub-sections.}
 
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-forms"]{Documenting Forms, Functions, Structure Types, and Values}

collects/scribblings/scribble/struct.scrbl

@@ -65,9 +65,10 @@ A @deftech{flow element} is either a @techlink{table}, an
 
              @item{An @deftech{element} can be a string, one of a few
                    symbols, an instance of @scheme[element] (possibly
-                   @scheme[link-element], etc.), a @techlink{delayed
+                   @scheme[link-element], etc.), a
-                   element}, or anything else allowed by the current
+                   @techlink{part-relative element}, a
-                   renderer.
+                   @techlink{delayed element}, or anything else
+                   allowed by the current renderer.
 
                    @itemize{
 
@@ -119,6 +120,17 @@ A @deftech{flow element} is either a @techlink{table}, an
                          processing to record information used by
                          later passes.}
 
+                   @item{A @deftech{part-relative element} is an
+                         instance of @scheme[part-relative-element],
+                         which has a procedure that is called in the
+                         @techlink{collect pass} of document
+                         processing to obtain @defterm{content} (i.e.,
+                         a list of @defterm{elements}). When the
+                         part-relative element's procedure is called,
+                         collected information is not yet available,
+                         but information about the enclosing parts is
+                         available.}
+
                    @item{A @deftech{delayed element} is an instance of
                          @scheme[delayed-element], which has a
                          procedure that is called in the
@@ -453,15 +465,37 @@ pass}.
 }
 
 
+@defstruct[part-relative-element ([resolve (collect-info? . -> . list?)]
+                                  [sizer (-> any/c)]
+                                  [plain (-> any/c)])]{
+
+Similar to @scheme[delayed-flow-element], but the replacement
+@techlink{content} is obtained in the @techlink{collect pass} by
+calling the function in the @scheme[resolve] field.
+
+The @scheme[resolve] function can call @scheme[collect-info-parents]
+to obtain a list of @techlink{parts} that enclose the element,
+starting with the nearest enclosing section. Functions like
+@scheme[part-collected-info] and @scheme[collected-info-number] can
+extract information like the part number.
+
+}
+
+
 @defstruct[(collect-element element) ([collect (collect-info . -> . any)])]{
 
 Like @scheme[element], but the @scheme[collect] procedure is called
 during the @techlink{collect pass}. The @scheme[collect] procedure
 normally calls @scheme[collect-put!].
 
+Unlike @scheme[delayed-element] or @scheme[part-relative-element], the
+element remains intact (i.e., it is not replaced) by either the
+@tech{collect pass} or @tech{resolve pass}.
+
 }
 
 
+
 @defstruct[collected-info ([number (listof (or/c false/c integer?))]
                            [parent (or/c false/c part?)]
                            [info any/c])]{
@@ -540,11 +574,15 @@ Returns the width in characters of the given @tech{element}.
 Returns the width in characters of the given @tech{flow element}.}
 
 
-@defstruct[collect-info ([ht any/c] [ext-ht any/c] [parts any/c] [tags any/c] [gen-prefix any/c])]{
+@defstruct[collect-info ([ht any/c] [ext-ht any/c] [parts any/c] 
+                         [tags any/c] [gen-prefix any/c] 
+                         [relatives any/c] 
+                         [parents (listof part?)])]{
 
 Encapsulates information accumulated (or being accumulated) from the
 @techlink{collect pass}. The fields are exposed, but not currently
-intended for external use.
+intended for external use, except that @scheme[collect-info-parents]
+is intended for external use.
 
 }
 
@@ -556,7 +594,25 @@ intended for external use.
 
 }
 
-@defproc[(collect-put! [ci collect-info?] [key any/c] [val any/c])
+@defproc[(info-key? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] is an @deftech{info key}: a list of
+at least two elements whose first element is a symbol. The result is
+@scheme[#f] otherwise.
+
+For a list that is an info tag, the interpretation of the second
+element of the list is effectively determined by the leading symbol,
+which classifies the key. However, a @scheme[#f] value as the second
+element has an extra meaning: collected information mapped by such
+info keys is not propagated out of the part where it is collected;
+that is, the information is available within the part and its
+sub-parts, but not in ancestor or sibling parts.
+
+Note that every @techlink{tag} is an info key.
+
+}
+
+@defproc[(collect-put! [ci collect-info?] [key info-key?] [val any/c])
          void?]{
 
 Registers information in @scheme[ci]. This procedure should be called
@@ -564,18 +620,48 @@ only during the @techlink{collect pass}.
 
 }
 
-@defproc[(resolve-get [p part?] [ri resolve-info?] [key any/c])
+@defproc[(resolve-get [p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
-         void?]{
+         any/c]{
 
 Extract information during the @techlink{resolve pass} or
 @techlink{render pass} for @scheme[p] from @scheme[ri], where the
 information was previously registered during the @techlink{collect
 pass}. See also @secref["passes"].
 
+The result is @scheme[#f] if the no value for the given key is found.
+Furthermore, the search failure is recorded for potential consistency
+reporting, such as when @exec{setup-plt} is used to build
+documentation.
+
 }
 
-@defproc[(resolve-get-keys [p part?] [ri resolve-info?] 
+@defproc[(resolve-search [dep-key any/c][p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
-                           [pred (any/c . -> . any/c)])
+         void?]{
+
+Like @scheme[resolve-get], but a shared @scheme[dep-key] groups
+multiple searches as a single request for the purposes of consistency
+reporting and dependency tracking. That is, a single success for the
+same @scheme[dep-key] means that all of the failed attempts for the
+same @scheme[dep-key] have been satisfied. However, for dependency
+checking, such as when using @exec{setup-plt} to re-build
+documentation, all attempts are recorded (in case external changes
+mean that an earlier attempt would succeed next time).
+
+}
+
+@defproc[(resolve-get/tentative [p (or/c part? false/c)] [ri resolve-info?] [key info-key?])
+         any/c]{
+
+Like @scheme[resolve-search], but without dependency tracking. For
+multi-document settings where dependencies are normally tracked, such
+as when using @exec{setup-plt} to build documentation, this function
+is suitable for use only for information within a single document.
+
+}
+
+@defproc[(resolve-get-keys [p (or/c part? false/c)]
+                           [ri resolve-info?] 
+                           [pred (info-key? . -> . any/c)])
          list?]{
 
 Applies @scheme[pred] to each key mapped for @scheme[p] in