
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 three definitions:
_help-desk_, and _open-url_.  These functions, when
invoked, dynamically load the help desk implementation, cache it, and
create and returns a help-desk frame. The frame they returns is the result
of invoking new-help-frame with the same startup-url that the stand-alone
help desk provides.

> (help-desk)

This just creates a help-desk frame open to the first page of the
documentation.

> (help-desk key lucky?)

This creates a help-desk frame and immediately performs a keyword and
indext exact-match search for key. If lucky? is #f, a normal search is
performed, otherwise a lucky search is performed. lucky? defaults to #t.

> (open-url url)

Opens a new help desk window and opens `url' in it.

-------------------------------------------------------------

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%
  help:doc-position^ 
    - contains only:
         user-defined-doc-position : string -> (union #f number)
      that specifies a weight to be used for each manual.
      #f means use the default weight

It exports

> help:help^

which contains three 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.

> (doc-collections-changed) - resets Help Desks's manuals index.
       This procedure flushes the cached keywords, hdindex, and
       doc.txt indicies and reloads them from scratch. It also
       calls user-defined-doc-position to resort the order of
       the manuals.

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.

> search-for-help/lucky :: (send a-help-frame search-for-help/lucky string type mode)
    - simulates a user-initiated lucky 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.


The _'blurb field_ of the _info.ss_ file
- - - - - - - - - - - - - - - - - - - - 

The 'blurb field of the info.txt file should be a list of xexprs (see the
xml documentation for information on the xexpr datatype) that correspond to
the html that help desk can parse. If a collection's info.ss file returns
such a list, the blurb is inserted into the ``installed components'' page
of the help desk documentation.

Each installed collection is listed in a "ul". The context of the
individual blurb field is this:

   `(li ()
        (font ((color "forest green")) 
              (b () ,name-of-collection))
        (br ())
        ,@blurbs)

where `name-of-collection' is the response of the 'name query to the
info.ss file and `blurbs' is the response of the 'blurb query to the
info.ss file.

The _'help-desk-message field_ of the _info.ss_ file
- - - - - - - - - - - - - - - - - - - - - - - - - -

This field must be a string that is displayed at the top of the Help Desk
window, in green, when the doc.txt file of this collection is displayed. It
should be a single line, describing how to load the library with a prefix
specifing the applicable language levels.


_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")

