
The _browser.ss_ library in the "browser" collection provides the
following procedures and classes for parsing and veiwing _HTML_ files.

The browser supports basic HTML commands, plus special Scheme
hyperlinks of the form <A MZSCHEME=sexpr>...</A>. When the user clicks
on such a link, the string `sexpr' is parsed as a Scheme program and
evaluated. Since `sexpr' is likely to contain Scheme strings, and
since escape characters are difficult for people to read, a vertical
bar (|) character in sexpr is converted to a double-quote (")
character before it is parsed. Thus,

  <A MZSCHEME="|This goes nowhere.|">Nowhere</A>

creates a "Nowhere" hyperlink, which executes the Scheme program

  "This goes nowhere."

The value of that program is a string. When a Scheme hyperlink returns
a string, it is parsed as a new HTML document. Thus, where the use
clicks on "Nowhere", the result is a new page that says "This goes
nowhere."

The browser also treats comment forms containing MZSCHEME=sexpr specially.
Whereas the <A MZSCHEME=sexpr>...</A> form executes the expression when the
user clicks, the MZSCHEME expression in a comment is executed
immediately. If the result is a string, the comment is replaced in the
input HTML stream with the content of the string. Thus,

 <!-- MZSCHEME="(format |<B>Here</B>: ~a| (current-directory))" -->

inserts the path of the current working directory into the containing
document (and "Here" is boldfaced). If the result is a snip instead of
a string, it replaces the comment in the document. Other types of
return values are ignored.

If the html file is being accessed as a file: url, the
current-load-relative-directory parameter is set to the directory
during the evaluation of the mzscheme code (in both examples)

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

> (open-url url) - Opens the given url
  (either a string, url record, or port) 
  in a vanilla browser frame and returns
  the frame.
   
----------------------------------------

> (hyper-text-mixin text%) - Extends the given text% class. The
   initializtion arguments are extended with a two new first
   arguments: a url or a port to be loaded into the text% object, and
   a top-level-window or #f to use as a parent for status
   dialogs. Unless the url is a string/url reprsenting a source file
   ending in ".txt", the loaded text is parsed as HTML.

   Sets the autowrap-bitmap to #f.
   
   An instance of a (hyper-text-mixin text%) class should be displayed
   only in an instance of a class created with `hyper-canvas-mixin'
   (described below).

   The mixin adds the following instance variables:

>   map-shift-style :: (send o map-shift-style start end shift-style)
     Maps the given style over the given range

>   make-link-style :: (send o make-link-style start end)
     Changes the style for the given range to the link style

>   get-url :: (send o get-url)
     Returns the URL displayed by the editor

>   get-title :: (send o get-title)
>   set-title :: (send o set-title string)
     Gets or sets the page's title

>   hyper-delta
     A style-delta% object; override it to set the link style

>   add-tag ::(send o add-tag name-string pos)
     Installs a tag.

>   find-tag :: (send o find-tag name-string/number)
     Finds the location of a tag in the buffer (where tags are
     installed in HTML with <A NAME="name">) and returns its
     position. If `name' is a number, the number is returned (assumed
     to be an offset rather than a tag). Otherwise, if the tag is not
     found, #f is returned.

>   remove-tag :: (send o remove-tag name)
     Removes a tag.

>   add-link :: (send o add-link start end url-string)
     Installs a hyperlink.

>   add-scheme-callback :: (send o add-scheme-callback start end scheme-string)
     Installs a Scheme evaluation hyperlink.

>   eval-scheme-string :: (send o eval-scheme-string string)
     Called to handle the <A SCHEME="expr">...</A> tag. Evaluates the
     string; if the result is a string, it is opened as an HTML
     page.

>  reload :: (send o reload)

    Reloads the current page.
     
----------------------------------------

> hyper-text% = (hyper-text-mixin text:keymap%)

  This is an extension of the keymap class, to support standard keybindings
  in the browser window.

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

> (hyper-canvas-mixin editor-canvas%) - Extends the given
  editor-canvas% class. The intialization arguments are unchanged.

  The canvas's parent should be an instance of a class derived with
  `hyper-panel-mixin' (described below).

  The mixin adds the following instance variables:

>   make-editor :: (send o make-editor url)
     Creates an hypertext editor for the canvas, called to navigate
     among hypertext pages. Changing the page changes the editor in
     the canvas, and the page history is maintained by keeping the old
     editors.
 
>   current-page :: (send o current-page)
     Returns a reprsentation of the currently displayed page, which
     includes a particular editor and a visible range within the
     editor.
 
>   goto-url :: (send o goto-url url relative-to-url)
     Changes to the given url, loading it by calling the `make-editor'
     method. If `relative-to-url' is not #f, it must be a URL for
     resolving `url' as a relative URL.

>   set-page :: (send o goto-page page notify?)
     Changes to the given page. If `notify?' is not #f, the canvas's
     parent is notified about the change by calling its `leaving-page'
     method.

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

> hyper-canvas% = (hyper-canvas-mixin editor-canvas%)

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

> (hyper-panel-mixin area-container%) - Extends the given area
  container class. The initialization arguments are unchanged, but
  initialization creates controls and a hyper text canvas.  The
  controls permit a user to move back and forth in the hypertext
  history.

  The mixin adds a initialization argument, info-line?, which is a
  boolean indicating whether the browser should contain a line to
  display special "DOCNOTE" tags in a page. Such tags are used
  primarily by the PLT documentation.

  The mixin adds the following instance variables:

>   make-canvas :: (send o make-canvas container)
     Creates the panel's hypertext canvas, an instance of a class
     derived using `hyper-canvas-mixin' (described above). This
     method is called during initialization.

>   make-control-bar-panel :: (send o make-control-bar-panel container)
     Create's the panel's sub-container for the control bar containing
     the navigation buttons. If #f is returned, the panel will have no
     control bar. The default method instantiates horizontal-panel%.

>   rewind :: (send o rewind)
     Goes back one page, if possible.

>   forward :: (send o forward)
     Goes forward one page, if possible.

>   get-canvas :: (send o get-canvas)
     Gets the hypertext canvas.

>   on-navigate :: (send o on-navigate)
     Callback that is invoked any time the displayed hypertext page
     changes (either by clicking on a link in the canvas or by
     `rewind' or `forward' calls).

>   leaving-page :: (send o leaving-page page new-page)
     This method is called by the hypertext canvas to notify the
     panel that the hypertext page changed. The `page' is #f
     if `new-page' is the first page for the canvas. See also
     `page->editor' (decsribed below).

>   filter-notes :: (send o filter-notes list-of-strings)
     Given the notes from a page as a list of strings (where
     each string is a note), returns a single string to print
     above the page.

>   reload :: (send o reload)

   Reloads the currently visible page by calling the reload method of
   the currently displayed hyper-text.
----------------------------------------

> hyper-panel% = (hyper-panel-mixin vertical-panel%)

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

> (editor->page editor) - Creates a page record for the given editor,
  suitable for use with the `set-page' method of hyper-canvas-mixin.

> (page->editor page) - Extracts the editor from a page record.

> (on-installer-run [proc]) - Parameter for a procedure to be invoked
  after the installer is run on a .plt file

> (bullet-size [n]) - Parameter controlling the point size of a
  bullet

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

The _browserr.ss_ library in the "browser" collection is a unitized version
of the code documented above. It imports these units:

 (import (function : mzlib:function^)
	 (string : mzlib:string^)
	 (file : mzlib:file^)
	 (url : mzlib:url^)
         (plt-installer : setup:plt-installer^)
	 (mred : mred^)
	 (framework : framework^))
