document the help collection's top-level modules

collects/help/help-utils.rkt

@@ -1,8 +1,8 @@
 #lang scheme/base
 
-;; This file provides the utilities that mzscheme's `help' form uses.
-;; It is required dynamically when used from mzscheme, to avoid the
-;; loading overhead, and to have mzscheme independent of having the
+;; This file provides the utilities that racket's `help' form uses.
+;; It is required dynamically when used from racket, to avoid the
+;; loading overhead, and to have racket independent of having the
 ;; documentation system.
 
 (require setup/xref

collects/help/private/buginfo.rkt

@@ -8,7 +8,6 @@
 (struct bri (label get-value) #:transparent)
 (define (bri-value bri) ((bri-get-value bri)))
 
-;; update with symbol/string assoc list
 (define bug-report-infos null)
 
 (define (set-bug-report-info! str thunk)

collects/help/search.rkt

@@ -1,4 +1,4 @@
-#lang scheme/base
+#lang racket/base
 
 (require setup/dirs net/sendurl net/uri-codec)
 (provide perform-search send-main-page)

collects/help/tests/test-docs-complete.rkt

@@ -1,7 +1,6 @@
 #lang racket/base
 (require rackunit/docs-complete)
 (check-docs (quote help/search))
-(check-docs (quote help/installer))
 (check-docs (quote help/help))
 (check-docs (quote help/help-utils))
 (check-docs (quote help/bug-report))

collects/scribblings/scribble/internals.scrbl

@@ -14,3 +14,4 @@
 @include-section["docreader.scrbl"]
 @include-section["xref.scrbl"]
 @include-section["config.scrbl"]
+@include-section["racket.scrbl"]

collects/scribblings/scribble/racket.scrbl

@@ -0,0 +1,26 @@
+#lang scribble/manual
+@(require "utils.ss"
+          (for-label help/search))
+
+@title[#:style 'toc]{Connecting to @filepath{racket}}
+
+This library is dynamically loaded by @tt{racket}'s
+@racket[help] function.
+
+@defmodule[help/help-utils]
+
+@defproc[(search-for [strs (listof string?)]) void?]{
+  Calls @racket[perform-search] after concatenating the
+  elements of @racket[strs] and adding spaces between them.
+}
+@defproc[(find-help/lib [id symbol?] [lib module-path?]) void?]{
+  Visits the documentation page for @racket[id] as an export of @racket[lib].
+}
+
+@defproc[(find-help [id identifier?]) void?]{
+  Visits the documentation for @racket[id].
+}
+
+@defproc[(go-to-main-page) void?]{
+  Visits the main entry page for the documentation.
+}

collects/scribblings/tools/documentation-utils.scrbl

@@ -0,0 +1,70 @@
+#lang scribble/doc
+@(require scribble/manual
+          (for-label racket
+                     net/sendurl))
+
+@title{Documentation Utilities}
+
+This section describes a bunch of utilities designed for use by DrRacket
+and its tools to connect to the scribble documentation. See also
+@racketmodname[scribble/xref].
+
+@section{Searching in the Docs}
+
+@defmodule[help/search]
+
+@defproc[(send-main-page [#:sub sub path-string? "index.html"]
+                         [#:notify notify (-> path? void)]
+                         [#:fragment fragment (or/c #f ??) #f]
+                         [#:query query (or/c #f ??) #f])
+         any]{
+  Visits the documentation file @racket[sub] in your browser. 
+  
+  This function builds a url that points into the main collection documentation
+  or into the user-specific documentation, depending on the @racket[sub] argument.
+  Once it finds the path, @racket[send-main-path] passes the path to
+  @racket[notify]. The @racket[fragment] and @racket[query] arguments are passed
+  to @racket[send-url/file], along with the url.
+}
+
+@defproc[(perform-search [str string?]
+                         [context (or/c #f
+                                        string?
+                                        (list/c string? string))
+                                  #f])
+         void?]{
+  Searches for @racket[str] in the documentation. The @racket[context] argument
+  supplies a context for the search or, if it is two strings, a context for
+  the search and a label for that context.
+}
+
+@section{Bug Reporting}
+@defmodule[help/bug-report]
+
+@defproc[(help-desk:report-bug [this-bug-id #f (or/c #f exact-positive-integer?)] 
+                               [#:frame-mixin 
+                                frame-mixin
+                                (make-mixin-contract frame%)
+                                values])
+         void?]{
+  Opens a bug report window to edit the but report identified by @racket[this-bug-id].
+  If @racket[this-bug-id] is @racket[#f], then creates a new bug id and uses that one.
+  
+  The @racket[frame-mixin] argument is passed the frame class before creating the window.
+}
+
+@defproc[(saved-bug-report-titles/ids) (listof brinfo?)]{
+  Returns a list of the saved bug reports.
+}
+
+@defproc[(discard-all-saved-bug-reports) void?]{
+  Deletes all of the saved bug reports, except those currently
+  open in frames.
+}
+
+@defstruct[brinfo ([title label-string?]
+                   [id number?]) #:transparent]{
+  A record representing a saved bug report. The @racket[id] field is suitable
+  for use with @racket[help-desk:report-bug] and the @racket[label] field
+  is suitable for use in a GUI control.
+}

collects/scribblings/tools/tools.scrbl

@@ -612,6 +612,8 @@ Check Syntax is a part of the DrRacket collection, but is implemented via the to
 @include-section["module-language-tools.scrbl"]
 @include-section["module-language.scrbl"]
 
+@include-section["documentation-utils.scrbl"]
+
 @section{Backwards compatibility}
 
 This section lists the bindings that begin with @tt{drscheme:} provided by the tools