From 2fe1c3b80d2d84a67f1384d42ea1f818d8466ee7 Mon Sep 17 00:00:00 2001 From: Robby Findler Date: Thu, 5 May 2011 14:56:18 -0500 Subject: [PATCH] document the help collection's top-level modules --- collects/help/help-utils.rkt | 6 +- collects/help/private/buginfo.rkt | 1 - collects/help/search.rkt | 2 +- collects/help/tests/test-docs-complete.rkt | 1 - collects/scribblings/scribble/internals.scrbl | 1 + collects/scribblings/scribble/racket.scrbl | 26 +++++++ .../tools/documentation-utils.scrbl | 70 +++++++++++++++++++ collects/scribblings/tools/tools.scrbl | 2 + 8 files changed, 103 insertions(+), 6 deletions(-) create mode 100644 collects/scribblings/scribble/racket.scrbl create mode 100644 collects/scribblings/tools/documentation-utils.scrbl diff --git a/collects/help/help-utils.rkt b/collects/help/help-utils.rkt index 67e7ec58bd..56f7ad5ee6 100644 --- a/collects/help/help-utils.rkt +++ b/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 diff --git a/collects/help/private/buginfo.rkt b/collects/help/private/buginfo.rkt index fc3c859493..06cf87b25f 100644 --- a/collects/help/private/buginfo.rkt +++ b/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) diff --git a/collects/help/search.rkt b/collects/help/search.rkt index 27eaf8fe06..d3d4e2168d 100644 --- a/collects/help/search.rkt +++ b/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) diff --git a/collects/help/tests/test-docs-complete.rkt b/collects/help/tests/test-docs-complete.rkt index 74f40b1987..7ef14b4a11 100644 --- a/collects/help/tests/test-docs-complete.rkt +++ b/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)) diff --git a/collects/scribblings/scribble/internals.scrbl b/collects/scribblings/scribble/internals.scrbl index c8d28210e0..3fd83800c2 100644 --- a/collects/scribblings/scribble/internals.scrbl +++ b/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"] \ No newline at end of file diff --git a/collects/scribblings/scribble/racket.scrbl b/collects/scribblings/scribble/racket.scrbl new file mode 100644 index 0000000000..5f71765e6d --- /dev/null +++ b/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. +} diff --git a/collects/scribblings/tools/documentation-utils.scrbl b/collects/scribblings/tools/documentation-utils.scrbl new file mode 100644 index 0000000000..338b0a310b --- /dev/null +++ b/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. +} diff --git a/collects/scribblings/tools/tools.scrbl b/collects/scribblings/tools/tools.scrbl index 79a91424aa..714333e1a5 100644 --- a/collects/scribblings/tools/tools.scrbl +++ b/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