From 2d12431c0da134e04ff62c5f4baa3ab86660f124 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 27 Dec 2012 08:57:24 -0600 Subject: [PATCH] move and fixup docs for the "help" collection --- .../help.scrbl} | 57 ++++++++++++++----- collects/help/info.rkt | 2 + collects/scribblings/scribble/internals.scrbl | 2 +- collects/scribblings/scribble/racket.scrbl | 25 -------- collects/scribblings/tools/tools.scrbl | 2 - 5 files changed, 46 insertions(+), 42 deletions(-) rename collects/{scribblings/tools/documentation-utils.scrbl => help/help.scrbl} (52%) delete mode 100644 collects/scribblings/scribble/racket.scrbl diff --git a/collects/scribblings/tools/documentation-utils.scrbl b/collects/help/help.scrbl similarity index 52% rename from collects/scribblings/tools/documentation-utils.scrbl rename to collects/help/help.scrbl index 98a15ac63b..b7f156add4 100644 --- a/collects/scribblings/tools/documentation-utils.scrbl +++ b/collects/help/help.scrbl @@ -1,36 +1,39 @@ #lang scribble/doc @(require scribble/manual (for-label racket + help/search + help/bug-report + help/help-utils net/sendurl)) -@title{Documentation Utilities} +@title{Help and 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]. +This section describes utilities designed to connect to documentation +and to support bug reports. See also @racketmodname[scribble/xref]. -@section{Searching in the Docs} + +@section{Searching in the Documentation} @defmodule[help/search] @defproc[(send-main-page [#:sub sub path-string? "index.html"] [#:notify notify (-> path? void) void] - [#:fragment fragment (or/c #f ??) #f] - [#:query query (or/c #f ??) #f]) + [#:fragment fragment (or/c #f string?) #f] + [#:query query (or/c #f string?) #f]) any]{ - Visits the documentation file @racket[sub] in your browser. + Visits the documentation file @racket[sub] in the user's browser. - This function builds a url that points into the main collection documentation + 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 + Once it finds the path, @racket[send-main-page] passes the path to @racket[notify]. The @racket[fragment] and @racket[query] arguments are passed - to @racket[send-url/file], along with the url. + to @racket[send-url/file], along with the URL. } @defproc[(perform-search [str string?] [context (or/c #f string? - (list/c string? string)) + (list/c string? string?)) #f]) void?]{ Searches for @racket[str] in the documentation. The @racket[context] argument @@ -38,6 +41,32 @@ and its tools to connect to the scribble documentation. See also the search and a label for that context. } +@; ------------------------------------------------------------ + +@section{Connecting to @exec{racket}} + +@defmodule[help/help-utils]{The @racketmodname[help/help-utils] +library is dynamically loaded by the @racket[help] form that is +available by default in @exec{racket}.} + +@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. +} + +@; ------------------------------------------------------------ + @section{Bug Reporting} @defmodule[help/bug-report] @@ -48,7 +77,7 @@ and its tools to connect to the scribble documentation. See also 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. + 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. } @@ -65,6 +94,6 @@ and its tools to connect to the scribble documentation. See also @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 + 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/help/info.rkt b/collects/help/info.rkt index ad8e934d90..a23289edc0 100644 --- a/collects/help/info.rkt +++ b/collects/help/info.rkt @@ -2,3 +2,5 @@ (define post-install-collection "installer.rkt") (define raco-commands '(("docs" help/help "search and view documentation" 110))) + +(define scribblings '(("help.scrbl"))) diff --git a/collects/scribblings/scribble/internals.scrbl b/collects/scribblings/scribble/internals.scrbl index 7cf095bcee..88a5bc5dde 100644 --- a/collects/scribblings/scribble/internals.scrbl +++ b/collects/scribblings/scribble/internals.scrbl @@ -15,4 +15,4 @@ @include-section["xref.scrbl"] @include-section["tag.scrbl"] @include-section["config.scrbl"] -@include-section["racket.scrbl"] + diff --git a/collects/scribblings/scribble/racket.scrbl b/collects/scribblings/scribble/racket.scrbl deleted file mode 100644 index 5ed9c1d9d3..0000000000 --- a/collects/scribblings/scribble/racket.scrbl +++ /dev/null @@ -1,25 +0,0 @@ -#lang scribble/manual -@(require "utils.rkt" (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/tools.scrbl b/collects/scribblings/tools/tools.scrbl index 91acdcd094..398147d191 100644 --- a/collects/scribblings/tools/tools.scrbl +++ b/collects/scribblings/tools/tools.scrbl @@ -926,8 +926,6 @@ not part of DrRacket proper, but one helper library is documented here. @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