added scheme/help

svn: r8016

original commit: f12a39d97b4d9f445f72a0240c633eab752447d8

collects/help/search.ss

@@ -10,8 +10,11 @@
          net/sendurl
          mzlib/contract)
 
+;; Restore the contract when keywords are supported:
+(provide generate-search-results)
+#;
 (provide/contract
- [generate-search-results (-> (listof string?) void?)])
+ [generate-search-results (-> (listof string?) #:xref xref? void?)])
 
 (define (make-extra-content desc)
   ;; Use `desc' to provide more details on the link:
@@ -55,7 +58,7 @@
                 (append (cdr search-results-files) 
                         (list (car search-results-files))))))
 
-(define (generate-search-results search-keys)
+(define (generate-search-results search-keys #:xref [xref #f])
   (let ([file (next-search-results-file)]
         [search-regexps (map (λ (x) (regexp (regexp-quote x #f))) search-keys)]
         [exact-search-regexps (map (λ (x) (regexp (format "^~a$" (regexp-quote x #f)))) search-keys)]
@@ -68,7 +71,7 @@
              (car search-keys)
              (map (λ (x) (format ", or ~a" x))
                   (cdr search-keys)))])])
-    (let ([x (load-xref)])
+    (let ([x (or xref (load-xref))])
       (xref-render
        x
        (decode `(,(title (format "Search results for ~a" search-key-string))

collects/scribble/latex-render.ss

@@ -70,6 +70,7 @@
         (printf "\\definecolor{LightGray}{rgb}{0.90,0.90,0.90}\n")
         (printf "\\newcommand{\\schemeinput}[1]{\\colorbox{LightGray}{\\hspace{-0.5ex}\\schemeinputbg{#1}\\hspace{-0.5ex}}}\n")
         (printf "\\newcommand{\\highlighted}[1]{\\colorbox{PaleBlue}{\\hspace{-0.5ex}\\schemeinputbg{#1}\\hspace{-0.5ex}}}\n")
+        (printf "\\newcommand{\\plainlink}[1]{#1}\n")
         (printf "\\newcommand{\\techlink}[1]{#1}\n")
         (printf "\\newcommand{\\indexlink}[1]{#1}\n")
         (printf "\\newcommand{\\imageleft}[1]{} % drop it\n")

collects/scribble/manual.ss

@@ -163,13 +163,15 @@
     (let ([s (apply string-append
                     (map (lambda (s) (if (string=? s "\n") " " s))
                          strs))])
+      (if (regexp-match? #rx"^ *$" s)
+          (make-element "schemeinputbg" (list (hspace (string-length s))))
           (let ([spaces (regexp-match-positions #rx"^ *" s)]
                 [end-spaces (regexp-match-positions #rx" *$" s)])
             (make-element
              "schemeinputbg"
              (list (hspace (cdar spaces))
                    (make-element "schemeinput" (list (substring s (cdar spaces) (caar end-spaces))))
-               (hspace (- (cdar end-spaces) (caar end-spaces))))))))
+                   (hspace (- (cdar end-spaces) (caar end-spaces)))))))))
 
   (define (verbatim s)
     (let ([strs (regexp-split #rx"\n" s)])
@@ -297,12 +299,6 @@
   (define (t . str)
     (decode-paragraph str))
 
-  (provide schememodule)
-  (define-syntax (schememodule stx)
-    (syntax-rules ()
-      [(_ body ...)
-       (code body ...)]))
-
   ;; ----------------------------------------
 
   (define-struct sig (tagstr))
@@ -771,23 +767,27 @@
        (proc
         (or (get-exporting-libraries render part ri) null)))))
 
-  (define (*deftogether boxes . body)
+  (define-struct (box-splice splice) (var-list))
+
+  (define (*deftogether boxes body-thunk)
     (make-splice
      (cons
       (make-table
        'boxed
        (map (lambda (box)
-              (unless (and (splice? box)
+              (unless (and (box-splice? box)
                            (= 1 (length (splice-run box)))
                            (table? (car (splice-run box)))
                            (eq? 'boxed (table-style (car (splice-run box)))))
-                (error 'deftogether "element is not a splice containing a single table: ~e" box))
+                (error 'deftogether "element is not a boxing splice containing a single table: ~e" box))
               (list (make-flow (list (make-table #f (table-flowss (car (splice-run box))))))))
             boxes))
-      body)))
+      (parameterize ([current-variable-list
+                      (apply append (map box-splice-var-list boxes))])
+        (body-thunk)))))
 
   (define-syntax-rule (deftogether (box ...) . body)
-    (*deftogether (list box ...) . body))
+    (*deftogether (list box ...) (lambda () (list . body))))
     
   (define (*defproc mode within-id
                     stx-ids prototypes arg-contractss arg-valss result-contracts content-thunk)
@@ -834,14 +834,14 @@
                                             (string-length (symbol->string (cadar s))))
                                          (string-length (symbol->string (caar s))))]
                                     [else 0])))))])
-      (parameterize ([current-variable-list
+      (let ([var-list (map (lambda (i)
-                      (map (lambda (i)
                              (and (pair? i)
                                   (if (keyword? (car i))
                                       (cadr i)
                                       (car i))))
                            (apply append (map cdr prototypes)))])
-        (make-splice
+        (parameterize ([current-variable-list var-list])
+          (make-box-splice
            (cons
             (make-table
              'boxed
@@ -1104,7 +1104,8 @@
                   [else
                    (cons #t (loop (cdr ps)
                                   (cons (caar ps) accum)))])))))
-          (content-thunk))))))
+            (content-thunk))
+           var-list)))))
 
   (define (make-target-element* inner-make-target-element stx-id content wrappers)
     (if (null? wrappers)
@@ -1148,7 +1149,7 @@
     (define (field-view f) (if (pair? (car f))
                                (make-shaped-parens (car f) #\[)
                                (car f)))
-    (make-splice
+    (make-box-splice
      (cons
       (make-table
        'boxed
@@ -1232,7 +1233,7 @@
                                             (to-element (field-view (car fields)))))))
                         (if (short-width . < . max-proto-width)
                             null
-                            (let loop ([fields fields])
+                            (let loop ([fields (if (null? fields) fields (cdr fields))])
                               (if (null? fields)
                                   null
                                   (cons (let ([fld (car fields)])
@@ -1310,11 +1311,12 @@
                            (make-flow (list (field-contract))))))))]
                 [else null]))
              fields field-contracts)))
-      (content-thunk))))
+      (content-thunk))
+     null))
 
   (define (*defthing stx-ids names form? result-contracts content-thunk)
     (define spacer (hspace 1))
-    (make-splice
+    (make-box-splice
      (cons
       (make-table
        'boxed
@@ -1349,12 +1351,13 @@
                               result-contract
                               (make-paragraph (list result-contract)))))))))))
             stx-ids names result-contracts))
-      (content-thunk))))
+      (content-thunk))
+     null))
 
   (define (meta-symbol? s) (memq s '(... ...+ ?)))
 
   (define (*defforms kw-id lits forms form-procs subs sub-procs content-thunk)
-    (parameterize ([current-variable-list
+    (let ([var-list
            (apply 
             append
             (map (lambda (form)
@@ -1372,9 +1375,10 @@
                       [(pair? form) (append (loop (car form))
                                             (loop (cdr form)))]
                       [else null])))
-                          forms))]
+                 forms))])
+      (parameterize ([current-variable-list var-list]
                      [current-meta-list '(... ...+)])
-      (make-splice
+        (make-box-splice
          (cons
           (make-table
            'boxed
@@ -1428,7 +1432,8 @@
                                                 "specgrammar"
                                                 (map car l)
                                                 (map cdr l))))))))))
-        (content-thunk)))))
+          (content-thunk))
+         var-list))))
   
   (define (*specsubform form has-kw? lits form-thunk subs sub-procs content-thunk)
     (parameterize ([current-variable-list
@@ -1619,26 +1624,43 @@
 
   (define-struct a-bib-entry (key val))
 
-  (define (bib-entry #:key key #:title title #:author author #:location location #:date date #:url [url #f])
+  (define (bib-entry #:key key 
+                     #:title title 
+                     #:author [author #f] 
+                     #:location [location #f]
+                     #:date [date #f]
+                     #:url [url #f])
     (make-a-bib-entry
      key
      (make-element
       #f
+      (append
+       (if author
            (list author
-            ", "
+                 ", ")
-            'ldquo
+           null)
+       (list 'ldquo
              title
-            "," 'rdquo " "
+             (if location
-            location
+                 "," 
-            ", "
+                 ".")
-            date
+             'rdquo)
-            "."
+       (if location
-            (if url
-                (make-element #f
            (list " "
-                                    (link url
+                 location
-                                          (tt url))))
+                 (if date 
-                "")))))
+                     ","
+                     "."))
+           null)
+       (if date
+           (list " "
+                 date
+                 ".")
+           null)
+       (if url
+           (list " "
+                 (link url (tt url)))
+           null)))))
 
   (define (bibliography #:tag [tag "doc-bibliography"] . citations)
     (make-unnumbered-part

collects/scribblings/scribble/basic.scrbl

@@ -29,7 +29,8 @@ For example, the @scheme[title] and @scheme[italic] functions might be
 called from Scheme as
 
 @schemeblock[
-(title #:tag "how-to" "How to Design " (italic "Great") " Programs")
+(title #:tag "how-to" 
+       "How to Design " (italic "Great") " Programs")
 ]
 
 or with an @elem["@"] expression as
@@ -54,11 +55,11 @@ have @schememodname[scribble/manual]).
          title-decl?]{
 
 Generates a @scheme[title-decl] to be picked up by @scheme[decode] or
-@scheme[decode-part].  The @scheme[pre-content]s list is parsed with
+@scheme[decode-part].  The @tech{decode}d @scheme[pre-content] (i.e.,
-@scheme[decode-content] for the title content. If @scheme[tag] is
+parsed with @scheme[decode-content]) supplies the title content. If
-@scheme[#f], a tag string is generated automatically from the
+@scheme[tag] is @scheme[#f], a tag string is generated automatically
-content. The tag string is combined with the symbol @scheme['part] to
+from the content. The tag string is combined with the symbol
-form the full tag.
+@scheme['part] to form the full tag.
 
 A style of @scheme['toc] causes sub-sections to be generated as
 separate pages in multi-page HTML output. A style of @scheme['index]
@@ -94,15 +95,18 @@ removed.}
  }
 
 @defproc[(item [pre-flow any/c] ...) item?]{
- Creates an item for use with @scheme[itemize]. The
+
- @scheme[pre-flow] list is parsed with @scheme[decode-flow].
+Creates an item for use with @scheme[itemize]. The @tech{decode}d
-}
+@scheme[pre-flow] (i.e., parsed with @scheme[decode-flow]) is the item
+content.}
+
 
 @defproc[(item? [v any/c]) boolean?]{
 
 Returns @scheme[#t] if @scheme[v] is an item produced by
 @scheme[item], @scheme[#f] otherwise.}
 
+
 @defform[(include-section module-path)]{ Requires @scheme[module-path]
  and returns its @scheme[doc] export (without making any imports
  visible to the enclosing context). Since this form expands to
@@ -112,9 +116,8 @@ Returns @scheme[#t] if @scheme[v] is an item produced by
 
 @section{Text Styles}
 
-@def-elem-proc[elem]{ Parses the @scheme[pre-content] list using
+@def-elem-proc[elem]{ Wraps the @tech{decode}d @scheme[pre-content] as
-@scheme[decode-content], and wraps the result as an element with
+an element with style @scheme[#f].}
-style @scheme[#f].}
 
 @def-elem-proc[aux-elem]{Like @scheme[elem], but creates an
 @scheme[aux-element].}
@@ -126,16 +129,16 @@ style @scheme[#f].}
 @def-style-proc[superscript]
 
 @defproc[(hspace [n nonnegative-exact-integer?]) element?]{
-Produces an element containing @scheme[n] spaces and style @scheme['hspace].
+
-}
+Produces an element containing @scheme[n] spaces and style
+@scheme['hspace].}
+
 
 @defproc[(span-class [style-name string?] [pre-content any/c] ...)
          element?]{
 
-Parses the @scheme[pre-content] list using @scheme[decode-content],
+Wraps the @tech{decode}d @scheme[pre-content] as an element with style
-and produces an element with style @scheme[style-name].
+@scheme[style-name].}
-
-}
 
 @; ------------------------------------------------------------------------
 
@@ -148,12 +151,10 @@ and produces an element with style @scheme[style-name].
 Creates an index element given a plain-text string---or list of
 strings for a hierarchy, such as @scheme['("strings" "plain")] for a
 ``plain'' entry until a more general ``strings'' entry. The strings
-also serve as the text to render in the index. The
+also serve as the text to render in the index. The @tech{decode}d
-@scheme[pre-content] list, as parsed by @scheme[decode-content] is the
+@scheme[pre-content] is the text to appear inline as the index
-text to appear in place of the element, to which the index entry
+target.}
-refers.
 
-}
 
 @defproc[(index* [words (listof string?)]
                  [word-contents (listof list?)]
@@ -168,7 +169,7 @@ the list of contents render in the index (in parallel to
          index-element?]{
 
 Like @scheme[index], but the word to index is determined by applying
-@scheme[content->string] on the parsed @scheme[pre-content] list.}
+@scheme[content->string] on the @tech{decode}d @scheme[pre-content].}
 
 
 @defproc[(section-index [word string?] ...)

collects/scribblings/scribble/decode.scrbl

@@ -30,6 +30,17 @@ special text conversions:
 
 }
 
+Some functions @deftech{decode} a sequence of @scheme[_pre-flow] or
+@scheme[_pre-content] arguments using @scheme[decode-flow] or
+@scheme[decode-content], respectively. For example, the @scheme[bold]
+function accepts any number of @scheme[_pre-content] arguments, so
+that in
+
+@verbatim["  @bold{``apple''}"]
+
+the @litchar{``apple''} argument is decoded to use fancy quotes, and
+then it is bolded.
+
 @defproc[(decode [lst list?]) part?]{
 
 Decodes a document, producing a part. In @scheme[lst], instances of

collects/scribblings/scribble/manual.scrbl

@@ -130,10 +130,10 @@ as a table/paragraph in typewriter font with the linebreaks specified
 by newline characters in @scheme[str]. ``Here strings'' are often
 useful with @scheme[verbatim].}
 
-@defproc[(schemefont [pre-content any/c] ...) element?]{Typesets the given
+@defproc[(schemefont [pre-content any/c] ...) element?]{Typesets
-content as uncolored, unhyperlinked Scheme. This procedure is useful
+@tech{decode}d @scheme[pre-content] as uncolored, unhyperlinked
-for typesetting things like @schemefont{#lang}, which are not
+Scheme. This procedure is useful for typesetting things like
-@scheme[read]able by themselves.}
+@schemefont{#lang}, which are not @scheme[read]able by themselves.}
 
 @defproc[(schemevalfont [pre-content any/c] ...) element?]{Like
 @scheme[schemefont], but colored as a value.}
@@ -144,6 +144,10 @@ for typesetting things like @schemefont{#lang}, which are not
 @defproc[(schemeidfont [pre-content any/c] ...) element?]{Like
 @scheme[schemefont], but colored as an identifier.}
 
+@defproc[(schemevarfont [pre-content any/c] ...) element?]{Like
+@scheme[schemefont], but colored as a variable (i.e., an argument or
+sub-form in a procedure being documented).}
+
 @defproc[(schemekeywordfont [pre-content any/c] ...) element?]{Like
 @scheme[schemefont], but colored as a syntactic form name.}
 
@@ -154,16 +158,16 @@ for typesetting things like @schemefont{#lang}, which are not
 @scheme[schemefont], but colored as meta-syntax, such as backquote or
 unquote.}
 
-@defproc[(procedure [pre-content any/c] ...) element?]{Typesets the given
+@defproc[(procedure [pre-content any/c] ...) element?]{Typesets
-content as a procedure name in a REPL result (e.g., in typewriter font
+@tech{decode}d @scheme[pre-content] as a procedure name in a REPL
-with a @litchar{#<procedure:} prefix and @litchar{>} suffix.).}
+result (e.g., in typewriter font with a @litchar{#<procedure:} prefix
+and @litchar{>} suffix.).}
 
-@defform[(var datum)]{Typesets @scheme[var] as an identifier that is
+@defform[(var datum)]{Typesets @scheme[datum] as an identifier that is
-an argument or sub-form in a procedure being
+an argument or sub-form in a procedure being documented. Normally, the
-documented. Normally, the @scheme[defproc] and @scheme[defform]
+@scheme[defproc] and @scheme[defform] arrange for @scheme[scheme] to
-arrange for @scheme[scheme] to format such identifiers automatically
+format such identifiers automatically in the description of the
-in the description of the procedure, but use @scheme[var] if that
+procedure, but use @scheme[var] if that cannot work for some reason.}
-cannot work for some reason.}
 
 @defform[(svar datum)]{Like @scheme[var], but for subform non-terminals
 in a form definition.}
@@ -175,8 +179,8 @@ in a form definition.}
 
 Produces a sequence of flow elements (encaptured in a @scheme[splice])
 to start the documentation for a module that can be @scheme[require]d
-using the path @scheme[id]. The @scheme[pre-flow]s list is parsed as a
+using the path @scheme[id]. The @tech{decode}d @scheme[pre-flow]s
-flow that documents the procedure (see @scheme[decode-flow]).
+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].
@@ -274,12 +278,13 @@ The @scheme[result-contract-expr-datum] is typeset via
 @scheme[schemeblock0], and it represents a contract on the procedure's
 result.
 
-The @scheme[pre-flow]s list is parsed as a flow that documents the
+The @tech{decode}d @scheme[pre-flow] documents the procedure. In this
-procedure. In this description, references to @svar[arg-id]s
+description, references to @svar[arg-id]s using @scheme[scheme],
-are typeset as procedure arguments.
+@scheme[schemeblock], @|etc| are typeset as procedure arguments.
 
-The typesetting of all data before the @scheme[pre-flow]s ignores the
+The typesetting of all information before the @scheme[pre-flow]s
-source layout.}
+ignores the source layout, except that the local formatting is
+preserved for contracts and default-values expressions.}
 
 
 @defform[(defproc* ([(id arg-spec ...)
@@ -309,14 +314,14 @@ for-label binding) are hyperlinked to this documentation.  The
 @scheme[require-for-label]) that determines the module binding being
 defined.
 
-The @scheme[pre-flow]s list is parsed as a flow that documents the
+The @tech{decode}d @scheme[pre-flow] documents the procedure. In this
-procedure. In this description, a reference to any identifier in
+description, a reference to any identifier in @scheme[datum] via
-@scheme[datum] is typeset as a sub-form non-terminal. If
+@scheme[scheme], @scheme[schemeblock], @|etc| is typeset as a sub-form
-@scheme[#:literals] clause is provided, however, instances of the
+non-terminal. If @scheme[#:literals] clause is provided, however,
-@scheme[literal-id]s are typeset normally.
+instances of the @scheme[literal-id]s are typeset normally.
 
 The typesetting of @scheme[(id . datum)] preserves the source
-layout, like @scheme[schemeblock], and unlike @scheme[defproc].}
+layout, like @scheme[schemeblock].}
 
 @defform[(defform* maybe-literals [(id . datum) ..+] pre-flow ...)]{
 

collects/setup/scribble-index.ss

@@ -13,6 +13,7 @@
          setup/main-collects)
 
 (provide load-xref
+         xref?
          xref-render
          xref-index
          xref-binding->definition-tag
@@ -27,6 +28,8 @@
 ;; Private:
 (define-struct xrefs (renderer ri))
 
+(define (xref? x) (xrefs? x))
+
 ;; ----------------------------------------
 ;; Xref loading