
The `help' collection provides tools for working with _Help Desk_.

_Running or Embedding Help Desk_
==============================

Loading the _help.ss_ library directly executes the Help Desk
program. 

The start-help-desk.ss file contains one unit that imports:

  mzlib:function^
  mzlib:string^
  mzlib:file^
  mzlib:url^ - not really in MzLib; it's in the "net" collection
  mred^
  framework^

and exports _help:start-help-desk^_, a signature with one definition:
_start-help-desk_. This function, when invoked, dynamically loads the help
desk implementation, caches it, creates and returns a help-desk frame. The
frame it returns is the result of invoking new-help-frame with the same
startup-url that the stand-alone help desk provides.

The _helpr.ss_ library provides the Help Desk as a unit with
the following imports:

  mzlib:function^
  mzlib:string^
  mzlib:file^
  mzlib:url^ - not really in MzLib; it's in the "net" collection
  mred^
  framework^
  (frame-mixin) - a mixin to be applied to Help Desk's frame, which
                  is derived from framework:frame:standard-menus%

It exports

> help:help^

which contains two items:

> (new-help-frame startup-url) - takes a url (a string or a url
       record) to use as the initial page for the window. Returns a
       frame% object (more specifically, an instance of
       framework:frame:standard-menus%). See below for information
       about public methods of this object.

> (open-url-from-user parent-window open-url-proc) - opens a dialog
       from which the user selects a url to open. The `parent'
       argument specifies a parent window for the dialog. The
       `open-url-proc' proecdure is called with a URL structure (see
       the URL library in the "net" collection). If `open-url-proc'
       raises an `exn:file-saved-instead' or `exn:cancelled' exception
       (as defined by the "browser" collections), it is caught. The
       dialog is not closed until an URL is opened sucessfully or the
       user clicks the Cancel button.

The frame returned by `new-help-frame' provides two extra methods:

> search-for-help :: (send a-help-frame search-for-help string type mode)
    - simulates a user-initiated search in the window, where `string'
    is the search input, `type' is 'keyword, 'keyword+index, or 'all,
    and `mode' is 'exact, 'contains, or 'regexp.

> goto-url :: (send a-help-frame goto-url url) - opens the given URL
    within the help frame.

All of the helpr.ss unit's imports must be initialized before the Help
Desk unit itself. For dynamic-linking convenience, the
`new-help-frame' and `open-url-from-user' procedures are also returned
as the values of the unit's initialization expression.

_Creating Help Desk Documentation_
==================================

Help Desk combines an HTML browser with a search engine. The search
engine looks for information in three places:

  * keyword directories

  * indexes

  * raw document source

A "keyword" (in this case) is a Scheme identifier, such as `cons' or
`define', and the keyword directory points to its definition.  Indexes
contain more general entries, such as "cut and paste" or "creating
help desk documents", and may map keywords to use sites rather than
definition sites. Searching through the raw document source (often
HTML source) may be useful as a last-ditch effort, but the point of
keyword directories and indexes is to avoid this as much as possible.

When the user searches on a keyword that reprsents a Scheme procedure,
class, or method, the search result provides immediate information
about the use of the keyword. For example, performing an exact keyword
search on "append" produces:

 In r5rs:
  (append list ...) in "R5RS - Pairs and lists"
 In mred:
  (send a-list-box append item data) in "append"
  (send a-list-box append item) in "append"
  (send a-list-control append item) in "append"

which shows that the standard Scheme `append' consumes any number of
lists, the `append' method of a list-box% object consumes one or two
arguments, etc. The user may click on search result lines to obtain
further information. Often, however, the immediate information is
sufficient, because the user merely wants the order of arguments for a
procedure or method.

The Help Desk locates the installed documentation as follows:

 * Help Desk checks each top-level collection to see if it contains a
   doc.txt file for collection-specific, text-based documentation.

 * Help Desk checks plt/collects/doc for more general, HTML-formatted
   documentaion.

The two documentation formats are described below.

The _doc.txt_ Format
--------------------

The Help Desk inspects each top-level collection to see if it contains
a doc.txt file. If so, the doc.txt file is parsed for index and
keyword entries. If a top-level collection contains a info.ss file
with a
>   'doc-sub-collections
field  (see the mzc manual for information about info.ss), then the
field's value should be a list of sub-collections to search for
doc.txt files (or even nested info.ss files).

No annotations are removed from a doc.txt file before it is presented
to the user. Thus, despite the annotations described below, "doc.txt"
is a WYSIWYG documentation format.

Index Entry Annotations
- - - - - - - - - - - -

An index entry is specified by surrounding the indexed phrase with
underscores. For example, the both of the section titles preceding
current are indexed: "Creating Help Desk Documentation" and "doc.txt".

Keyword Entry Annotations
- - - - - - - - - - - - -

A keyword entry is specified using

  >

at the beginning of a line. After the ">", put an S-expression that
contains only symbols. (Spaces between ">" and the S-expression are
ignored.) The leftmost atom must be a symbol, and this symbol is used
as the key for the entry, whereas the whole S-expression is displayed
when the user searches on the key. (Note: the S-expression is read
with `read-accept-bar-quote' turned off, since | is useful for showing
alternatives.)

For example, a keyword entry for `cons' might have the following form:

 > (cons v list) - Constructs a new list by ...

When the user searches on "cons", the Help Desk will display a link
that looks something like

 In mytools collection:
   (cons v list) in "doc.txt"
    ^^^^^^^^^^^
Note that a search on "list" will not reveal this entry, because
"cons" is used as the key, not the whole S-expression.

To create a keyword entry where the key is *not* the leftmost symbol
in the S-expression, use the follwing form:

  > keyword :: S-expression

where `keyword' is a Scheme symbol. The special "::" indicator
instructs the Help Desk to look ahead one more S-expression. For
example, documentation for a `set-title' method might appear as
follows:

  > set-title :: (send o set-title string) - sets the title

The "(send o set-title string)" part allows a Help Desk user to learn
about the calling convention of `set-title' without accessing the
documentation directly.

The HTML Format
---------------

HTML documention is put in its own sub-directory in the `doc'
collection. For example, the MzScheme manual is in the directory
plt/collects/doc/mzscheme. The starting point for each manual must be
called "index.htm" (no "l").

In addition to HTML files, a manual directory can contain a "keywords"
file, which maps keywords to HTML pages and labels, and an "hdindex"
file, which similarly maps index entries HTML pages.

The _"keywords"_ File
- - - - - - - - - - -

The "keywords" file must contain one S-expression (not evaluated),
which is a list of keyword entries. Each keyword entry is a list of
five values:

  * keyword - a string, e.g., "cons"

  * result display - a string to be displayed in the search results
    window when the user searches on the keyword, e.g., "(cons v
    list)"

  * HTML file - a file name relative to the manual's directory, e.g.,
    "node198.htm"

  * HTML label - a string reprsenting a label within the HTML file

  * page title - a string presenting the title of the HTML page, e.g.,
    "List Procedures"

See plt/collects/doc/mzscheme/keywords for an example.

The _"hdindex"_ File
- - - - - - - - - -

The "hdindex" file is similar to the "keywords" file; it must contain
one S-expression (not evaluated), which is a list of index entries.
Each index entry is a list of four values:

  * indexed item - a string, e.g., "creating help desk documents"

  * HTML file - a file name relative to the manual's directory, e.g.,
    "node198.htm"

  * HTML label - a string reprsenting a label within the HTML file

  * page title - a string presenting the title of the HTML page, e.g.,
    "How to Create Help Desk Documents"

See plt/collects/doc/mzscheme/hdindex for an example.

_Help Desk Entry Points_
========================

 The Help Desk documentation base supports the following entry
 points, which may be used by applications.

> Help Desk Start Page

  Found at (build-path (collection-path "doc" "help") "index.html")

> Help Desk Release Notes
 
  Found at (build-path (collection-path "doc" "help" "release") "notes.html")

