diff --git a/collects/scribble/base-render.ss b/collects/scribble/base-render.ss index b48c795d0b..8fa4444c37 100644 --- a/collects/scribble/base-render.ss +++ b/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) diff --git a/collects/scribble/struct.ss b/collects/scribble/struct.ss index 7eabde40ba..0f2b935b80 100644 --- a/collects/scribble/struct.ss +++ b/collects/scribble/struct.ss @@ -77,13 +77,7 @@ (provide (struct-out collect-info) - (struct-out resolve-info) - part-collected-info - collect-put! - resolve-get - resolve-search - resolve-get/tentative - resolve-get-keys) + (struct-out resolve-info)) ;; ---------------------------------------- @@ -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)]) + ) diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index df234cb116..b84632be59 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/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} diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl index 7435402f40..c3e296bb60 100644 --- a/collects/scribblings/scribble/struct.scrbl +++ b/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 - element}, or anything else allowed by the current - renderer. + @scheme[link-element], etc.), a + @techlink{part-relative element}, a + @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]) - void?]{ +@defproc[(resolve-get [p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) + 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?] - [pred (any/c . -> . any/c)]) +@defproc[(resolve-search [dep-key any/c][p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) + 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