CONTENTS:
This is an "unofficial" version 2.5.4a of Joust.  It extends Joust
so as to support continuous vertical dotted lines when menu entries 
"wrap" over more than one line.

ORIGINAL JOUST AUTHOR:
Ivan Peters
http://www.ivanpeters.com

AUTHOR OF 2.5.4a CHANGES:
W. Charles Roth, 27 April 2001
roth@thedance.net
http://www.thedance.net/joust

COPYRIGHT:
The changes from 2.5.4 to 2.5.4a are Copyright (C) 2001 by W. Charles Roth.
They (the *changes*) may be used by anyone for any purpose, including 
copying, distributing, modification, or inclusion in other software.
(This copyright notice may considered equivalent to the "Open Source"
MIT Artistic license.  See www.opensource.org for details.)  The
author of these changes is not responsible for any damages, direct
or incidental, that may result from the use of this software.
Use at your own risk.  Caveat Implementor!

The original copyright on Joust proper is owned by Ivan Peters; see
http://www.ivanpeters.com for further information.

WHAT IS THIS REALLY?
Joust is a wonderful javascript package for producing an "outliner"
navigation frame, and we all owe Ivan a virtual beer for producing it.
(Again, for details see http://www.ivanpeters.com.)

It has, in this author's opinion, one distinct short-coming: when 
displaying menus with linewrap (attribute multiLine = true), the
nice vertical dotted lines get interrupted, leaving a rather unaesthetic
display.

The changes implemented by this author cause the dotted vertical line
to appear continuous.  If you are using Joust with line-wrapped menus,
this can be a substantial improvement on the look and feel of your
site.

TECHNICAL DETAILS AND CAVEATS
This version is *not* a true rewrite of Joust to implement the "proper"
way of handling continuous dotted lines; in programmerese, it may be
considered a "hack".  Nonetheless it points the way to a proper solution,
and it is the author's hope that it will be useful to Ivan for future
official versions of Joust.

This version treats all menus as line-wrapped menus, i.e. regardless of
the setting of multiLine, menus are *always* wrapped if they would go
off the edge of the navigation frame.  Also, the browser "hasDHTML" 
property is always set to false -- (a) because the changes for
continuous dotted lines seem to upset the hasDHTML calculation of
element heights, which in turn is used to control scrolling, and
(b) all browsers seem to operate as fast or faster with hasDHTML
turned off.

Normally Joust writes each horizontal "slice" of the outline display
as simply a line of HTML, with a <BR> at the end.  2.5.4a writes each
"slice" as an individual one-row <TABLE>; each level of indentation
gets its own cell in the table.  The actual menu text becomes the last
cell in the table.

Now, by itself, this change would still leave big gaps in the vertical
lines whenever a line of menu text wrapped.  So we added to each
indentation cell (that contains any of the icons that imply a vertical
line below) a background image, longline4.gif.  This image is 18 pixels
wide by 128 pixels high; the top 16 rows are blank (transparent) so as
to overlay (underlay?) the foreground image in the cell.  The rest of the
image has the continuous dotted vertical line from the 17th to the last
row.

(Originally it was thought that a smaller background image could be used
to "tile" the cell regardless of the height; but due to bugs in the
implementation of Netscape 4's table cell background image handling,
that proved impossible.  So the reverse method was used; instead tiling
a small image, we truncate a larger image.  If the wrapped version of the
text extends more than 128 pixels high, gaps will appear again; this can
be fixed by simply making the longline4.gif image "longer".)

This change has been tested on Netscape 4.x, Netscape 6.01, IE 4.01, 
and IE 5.01.  It fails gracefully (the background images do not appear, 
but everything else works as usual) under Netscape 3.

CODE CHANGES
All of the code changes are in the file index.htm, and are clearly marked
with javascript comments "//WCR".  Changes were made to the following
functions:
   MIDraw
   MenuDrawALevel
   initOutlineIcons
   browserInfo

An image (background vertical line) was added, images/menu/win/longline4.gif.

The affected functions were also reformatted to use indentation levels
of 3 spaces (instead of tabs), and to run no longer than 80 characters
per line, for readability purposes.

POSSIBLE PROBLEMS AND CONCERNS
   1. This version has not been tested on a Mac -- in particular,
      the background image is provided only for the menu/win
      directory -- this may need to fixed or added for Mac, OS/2, etc.

   2. As mentioned, this version effectively forces multiLine mode on.
      In theory it would be possible to allow either mode, either
      by writing different code sections in the affected functions
      (listed above), or by hacking the per-horizontal-strip tables
      to an arbitrary width (perhaps by putting in a row that has
      a very wide 1-pixel high image).  As this author had limited
      time and a clear need for *only* multiLine, no work was done
      on this.  (Hey, I said it was a hack! <g>)

   3. Also as mentioned, the browser hasDHTML property is always off
      (false).  The DHTML element-height(??) calculation is too deep
      for me to figure out, and besides, the browsers all seem to run
      faster with DHTML off anyway. <g>

   4. On some browsers, the vertical line will occasionally show
      a heavier-looking dot (if you look really closely).  This happens
      where the pixel line-height of the wrapped menu text is an odd
      number: the last dot from the cell above appears immediately
      adjacent to the first dot in the cell below.  Probably impossible
      to fix, but it's barely noticeable.

THOUGHTS FOR FUTURE CHANGES
This is just the author's place to sound-off on ways to make it easier
to work with and extend Joust.  Apply the appropriate quantity of
NaCl.

   1. Separate all Joust functions into a "joust.js" file that is
      included via a <SCRIPT SRC="..."> tag.  Those of us doing 
      really complicated websites/framesets need to do that anyway.
      Ideally, Joust would be provided both ways: as a complete
      index.htm file that can just be tinkered with, *or* as a
      completely separate module that the sophisticated frameset
      builder just includes and calls.

   2. Reformat joust functions with spaces instead of tabs, and
      apply the 80 column rule.  

   3. Store the full text name of the target window for a Joust link
      as a property of 'theMenu', rather than implicitly accessing
      it in the code as "self.xyz" or whatever, and then use eval()
      to evaluate the object at runtime.  We had to hack many other
      lines of Joust code because we had a two-level, dynamically
      written frameset (frame sizes changed depending on what the
      user was doing), and native Joust window references couldn't
      handle that.

   4. The folder and page icons are cute, but in practice for any 
      professional website, IMHO they're the first thing to get 
      ditched.  They take up scare horizontal real estate, and
      they're effectively redundant; the +/- icons tell the real
      story about whether an entry is a leaf or a node.  So I
      suggest a very simple switch to turn them off or on right
      from the start.