377 lines
13 KiB
Plaintext
377 lines
13 KiB
Plaintext
The `help' collection provides tools for PLT _Help Desk_.
|
|
|
|
The file help.ss is used to build the Help Desk launcher, which
|
|
uses MrEd. The file help-bg.ss is used to build a `background'
|
|
Help Desk launcher, which uses MzScheme.
|
|
|
|
There are two modules that Help Desk clients may load.
|
|
The file `help-desk-mz.ss' provides a set of functions that
|
|
use only MzScheme. The file `help-desk.ss' provides all the
|
|
functions provided by `help-desk-mz.ss', plus some that rely
|
|
on MrEd.
|
|
|
|
The MrEd-dependent functions provided by `help-desk.ss' are:
|
|
|
|
> search-for-docs : hd-cookie search-string search-type match-type lucky? -> void
|
|
|
|
The `hd-cookie' argument is returned by `start-help-server', below.
|
|
Searches for `search-string' in the documentation, using `search-type'
|
|
and `match-type', and displays result in the Help Desk browser. The
|
|
`search-type' is one of "keyword", "keyword-index", or "keyword-index-text".
|
|
The `match-type' is one of "exact-match", "containing-match", or
|
|
"regexp-match". The `lucky?' parameter indicates whether to do a
|
|
lucky search or not; it is considered true for any value other than #f.
|
|
Side effect: the `search-type' and `match-type' values are stored as
|
|
preferences, reflected in the Help Desk search pane as the values
|
|
of options shown in drop-down lists.
|
|
|
|
> goto-manual-link : hd-cookie manual index-key -> void
|
|
|
|
The `hd-cookie' argument is returned by `start-help-server', below.
|
|
The `manual' and `index-key' entries are strings. The `manual'
|
|
argument is the string name of a doc collection, or "help";
|
|
the second is an index entry in that manual. When called,
|
|
this procedure starts a Help Desk browser with the appropriate
|
|
manual page shown in the lower frame, if the requested entry
|
|
exists. Otherwise, an error occurs.
|
|
|
|
> goto-hd-location : hd-cookie sym -> void
|
|
|
|
The `hd-cookie' argument is returned by `start-help-server',
|
|
below. The argument `sym' is a symbol in
|
|
|
|
'(hd-tour release-notes plt-license front-page)
|
|
|
|
Sends a Help Desk browser on the page suggested by `sym',
|
|
creating one if necessary.
|
|
|
|
> help-desk-browser : hd-cookie -> void
|
|
|
|
Starts the Help Desk browser on the Help Desk home page. The
|
|
`hd-cookie' argument is obtained from `start-help-server', described
|
|
below. If the user's default browser does not contact the
|
|
Help Desk server within a certain time period, an internal PLT
|
|
browser is started instead.
|
|
|
|
The following functions are provided by both `help-desk-mz.ss' and
|
|
`help-desk.ss'. These functions rely only on MzScheme:
|
|
|
|
_Server functions_
|
|
------------------
|
|
|
|
> start-help-server : (browser-frame-mixin . -> . hd-cookie)
|
|
|
|
Starts the Web server for Help Desk. The optional argument
|
|
`remote?' indicates whether remote connections should be
|
|
allowed; the default is #f. The optional argument `port' is
|
|
an exact integer or #f, the default. If a port number is
|
|
given, the server attempts to use that port; otherwise, the
|
|
server attempts to find an available port. The optional
|
|
argument browser-frame-mixin is mixed into the internal
|
|
browser's frame class, if one is created.
|
|
|
|
The return value is a structure that contains instance
|
|
information about the server. The cookie needs to be passed
|
|
to some other Help Desk functions described here. If the
|
|
specified port is unavailable, or the server cannot find an
|
|
unused port, an error occurs.
|
|
|
|
> hd-cookie-port : hd-cookie -> number
|
|
|
|
Given a Help Desk server cookie, returns the port number
|
|
used by the server.
|
|
|
|
> hd-cookie-shutdown-server : hd-cookie -> (-> void)
|
|
|
|
Given a Help Desk server cookie, returns a thunk that
|
|
shuts down the server when called.
|
|
|
|
> hd-cookie-find-browser : (hd-cookie?
|
|
. -> .
|
|
(-> (union false? (is-a?/c frame%))))
|
|
|
|
Returns a procedure that finds a help desk browser
|
|
window. If none is available, returns #f.
|
|
|
|
> hd-cookie? : obj -> boolean
|
|
|
|
Returns #t if `obj' is a Help Desk cookie, #f otherwise.
|
|
|
|
> visit-url-in-browser : (hd-cookie? string? . -> . void?)
|
|
|
|
Visits the second argument in a browser, creating a
|
|
browser window if necessary.
|
|
|
|
> visit-url-in-new-browser : (hd-cookie? string? . -> . void?)
|
|
|
|
Visits the second argument in a browser, always creating a
|
|
new browser window.
|
|
|
|
_Manual ordering_
|
|
-----------------
|
|
|
|
> standard-html-doc-position : string -> number
|
|
|
|
Given a manual name, returns a number (possibly negative)
|
|
that indicates its standard search order position.
|
|
|
|
> user-defined-doc-position : string -> (union number #f)
|
|
|
|
Like standard-html-doc-position, but returns a weight
|
|
only if the user has assigned one using `set-doc-position!',
|
|
described below. If the user has not set a weight for the
|
|
manual, #f is returned. If the manual is not among `known-docs'
|
|
(see below), an error occurs.
|
|
|
|
> set-doc-position! : string number -> void
|
|
|
|
Sets the manual, indicated by the string argument, to
|
|
use the search order position given by the number argument.
|
|
If the manual is not among `known-docs' (see below), an
|
|
error occurs.
|
|
|
|
> reset-doc-positions! : -> void
|
|
|
|
Removes all the user-defined document weights that may have
|
|
been set using `set-doc-position!', above.
|
|
|
|
> known-docs : (listof (cons string string))
|
|
|
|
A list of pairs, where each pair consists of a short-form name of a
|
|
manual, suitable to pass to `standard-html-doc-position',
|
|
`user-defined-doc-position', or `set-doc-position', and
|
|
a full name for the manual.
|
|
|
|
_Search functions_
|
|
------------------
|
|
|
|
> do-search : search-string num bool bool val f1 f2 f3 f4 -> (union string #f)
|
|
|
|
Performs a search for `search-string' in the documentation, and returns either
|
|
a string containing HTML or #f. More details are provided in the file
|
|
search.ss in the private subdirectory of the help collection.
|
|
|
|
> doc-collections-changed : -> void
|
|
|
|
Calling this procedure indicates to the Help Desk search engine that
|
|
the documentation collections have changed.
|
|
|
|
_Important Help Desk URLs_
|
|
---------------------------
|
|
|
|
> make-home-page-url : number -> string
|
|
|
|
given the port of the help desk server (from the cookie),
|
|
returns a url for the homepage of help desk.
|
|
|
|
_Manual listing_
|
|
----------------
|
|
|
|
> (find-manuals)
|
|
|
|
Returns HTML showing the installed documentation.
|
|
|
|
_Manual search functions_
|
|
-------------------------
|
|
|
|
These functions are used to search for particular portions of
|
|
documentation.
|
|
|
|
> (finddoc manual index-key label)
|
|
This procedure accepts three strings. The first is the name of
|
|
a doc collection, the second is an index entry in that manual, and
|
|
the final is a descriptive string. It returns a string representation
|
|
of an anchor (in HTML) that points to that index entry in the manual.
|
|
If the manual is not found, or the index-key is not in the manual,
|
|
it returns html code that shows an error. Because the link is
|
|
a "file:" link, it cannot link to a particular anchor in the target.
|
|
Note that "help" is not a valid value for `manual', because
|
|
Help Desk content is not stored in a doc collection.
|
|
|
|
> (findreldoc to-doc-path manual index-key label)
|
|
Like `finddoc', but `to-doc-path' is a Unix-style relative path that
|
|
reaches the "docs" collection. The resulting link is relative, and
|
|
it can point to a specific anchor in the target.
|
|
|
|
> (finddoc-page-anchor manual index-key)
|
|
This procedure accepts two strings. The `manual' argument is the name
|
|
of a doc collection, or "help"; the second is an index entry in that
|
|
manual. It returns a forward-slashed path to the manual or Help Desk
|
|
entry, to be passed to the Help Desk web server. For manuals in the
|
|
doc collection, that path is of the form "/doc/manual/page#anchor";
|
|
for Help Desk entries, that path is of the form
|
|
"/servlets/<rest-of-path>#anchor". If the manual is not found, or the
|
|
index-key is not in the manual, an error occurs.
|
|
|
|
> (finddoc-page manual index-key)
|
|
Like `finddoc-page-anchor', but returns only the page, without
|
|
an anchor.
|
|
|
|
_Supplemental Help Desk functions_
|
|
----------------------------------
|
|
|
|
> (set-bug-report-info! string thunk)
|
|
|
|
Adds dynamic information used when submitting a bug
|
|
report.
|
|
|
|
The string is the label for the information and the thunk
|
|
must return a string that is the current value of the
|
|
information.
|
|
|
|
> (help-desk:installed-components)
|
|
|
|
It returns a string of XHTML with documentation extracted from the
|
|
_'blurb_ fields of the info.ss files in each collection.
|
|
|
|
_Creating Help Desk Documentation in doc.txt files_
|
|
===================================================
|
|
|
|
Help Desk reads doc.txt files that are named by info.ss
|
|
files (in PLaneT, or in collections or their
|
|
subcollections). The info.ss file should have a line:
|
|
|
|
(define doc.txt "filename.txt")
|
|
|
|
directing Help Desk to read the file named "filename.txt"
|
|
(usually, by convention these files are named "doc.txt").
|
|
|
|
Index Entry Annotations
|
|
- - - - - - - - - - - -
|
|
|
|
An index entry is specified by surrounding the indexed phrase with
|
|
underscores, as for the current portion of this file.
|
|
|
|
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 following 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.
|
|
|
|
_Creating Help Desk Documentation in HTML format_
|
|
===================================================
|
|
|
|
Help Desk looks for html documentation in two places:
|
|
|
|
1) If an info.ss file defines _'html-docs_ to be a list of
|
|
path strings, Help Desk looks inside those directories
|
|
for html documentation (the paths are treated as
|
|
relative to the location of the info.ss file)
|
|
|
|
2) Help Desk also looks inside each sub-directory in any
|
|
`doc' collection (Help Desk searches all doc
|
|
collections, not just the first one, unlike
|
|
`collection-path').
|
|
|
|
The starting point for each manual must be called either:
|
|
|
|
index.htm
|
|
index.html
|
|
<jobname>.html, where <jobname>-Z-H-1.html
|
|
also exists in the directory
|
|
|
|
The last is to support tex2page generation of manuals.
|
|
|
|
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 representing a label within the HTML file
|
|
|
|
* page title - a string presenting the title of the HTML page, e.g.,
|
|
"List Procedures"
|
|
|
|
See plt/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 strings:
|
|
|
|
* indexed item - e.g., "creating help desk documents"
|
|
|
|
* HTML file - a file name (represented as a string)
|
|
relative to the manual's directory, e.g., "node198.htm"
|
|
|
|
* HTML label - a label within the HTML file
|
|
|
|
* page title - the title of the HTML page, e.g.,
|
|
"How to Create Help Desk Documents"
|
|
|
|
See plt/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.
|
|
|
|
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
|
|
results 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
|
|
specifying the applicable language levels.
|
|
|