Installing JUMBO-core

1998-01-26

This is an alpha release of JUMBO-core prior to a beta on about 1998-02-04 for a virtual lecture I am giving on XML/CML. The primary purpose is to investigate JUMBO's portability and installation, especially with the SAX software recently developed on XML-DEV by David Megginson. You will need to be familiar with XML and current tools. This distribution includes:

Core JUMBO Java packages in *.class form (util, euclid, simplegraph, sgml)
JUMBO-HTML *.class (sgml.html)
A few test examples
configuration files (jumbo/mimetypes.xml, jumbo/config.xml)

You should also have installed one or more of the following parsers (deliberately not included :-):

AElfred (David Megginson)
Lark (Tim Bray)
MSXML (Microsoft)
NXP (Norbert Mikula)
XP (James Clark)

I have not tested all of these fully and cannot guarantee that the Jumbo-SAX-Parser architecture works for all examples. Feedback on problems would be much appreciated.

JUMBO architecture

JUMBO-CORE is a general-purpose, application-independent element-oriented XML browser, editor with hooks to build further applications. NOTE: JUMBO is not specifically for chemistry and will browse and render any XML document. Typical examples of real documents are given below. JUMBO's main emphasis is on per-element display rather than high-performance text rendering. For textual documents you may wish to combine the use of JUMBO with other packages, tools or browsers.

JUMBO has an elementary (and incomplete) XML parser, sufficient for its own configuration files. I intend it to be used with the SAX API so that any SAX-compliant parser can be used at runtime. This release is the first time, so please report any problems (SAX is only 2 weeks old!). At present David Megginson has written SAX interfaces for AElfred, Lark, NXP and MSXML (*Driver.java). To test these he wrote SAXDemo.java, which I have hacked to produce JumboSAX.java. JumboSAX initiates the parsing and returns the result to Jumbo. James Clark has written a SAX interface to XP (I have only just downloaded this and not installed it in JUMBO).

JUMBO-CORE's main package is jumbo.sgml. This manages browser functions, the parser, identifies elementTypes for nodes, builds a tree and manages interaction. Key classes are SGMLNode , SGMLTree,
SGMLAttlist, and TOCPanel. Applications extend these by subclassing SGMLNode, and providing element-specific classes, which are loaded when elementTypes are discovered in the document. Major current packages extending JUMBO are:

jumbo.sgml.html (HTML V2.0). This supports well-formed HTML at about V2.0 level (but no tables or forms). Rendering is readable but not optimised for performance or beauty. JUMBO-HTML is included in the distribution.
jumbo.tecml (Technical Markup Language). This is aimed at technical and scientific applications provides strong data typing (FLOAT, DATE, etc.) with UNITS and structuring (ARRAY and LIST). Some commonly used data types are also included: BIB, PERSON, FIGURE, etc. NOT included
jumbo.cml (Chemical MarkupLanguage). This provides support for molecular applications. NOT included.
jumbo.chemime (Chemical MIME). Classes to convert non-XML files (chemical/x-*) into XML trees on the fly. NOT Included.
jumbo.vhg (Virtual HyperGlossary). Support for XML-based terminology including ISO12620 terms. NOT included.

Only jumbo.sgml.html is present in the alpha release. The others will probably be available for the beta. In any case it is best to download and install JUMBO-* sequentially.

JUMBO provides support for XLL (XML-LINK) in both TEI pointers and XML-LINK. There are a few features in Xptrs not yet implemented because the spec is due to be revisited. JUMBO provides implementations of most SIMPLE options (EMBED is problematic for non-textual applications), but has no special support for EXTENDED or GROUP. No XLL examples are provided for the alpha, but will be in the beta.

JUMBO has embryonic support for XSL (XML-STYLE). It can parse XSL files and display them as trees, but does provide rendering for documents. JUMBO is likely to develop XSL for on-screen applications and document processing rather than formatting. No XSL examples will be provided in this release.

Instructions

Unpack the JUMBO distribution into a directory (here called mydir/demos).This should contain at least:

jumbo (directory, with subdirectories for class files)
icons (directory for icons on a per-package basis)
scene1.sgm (Act1, Scene1 from Julius Caesar - courtesy Jon Bosak) NOT included, since Jon (rightly) wants to keep the distribution intact).
Lark.xml (Lark documentation in XML - courtesy Tim Bray): NOT included until I get permission
install.xml (an early version of this document's HTML source in WF XML.)
jumbo/mimetypes.xml (MIME types read by JUMBO)
jumbo/config.xml (configuration file for JUMBO, especially Parsers)

Your CLASSPATH should include mydir/demos which should resolve all relevant files. JUMBO is both an application and an applet, but results are not guaranteed with the latter as Netscape throws a security exception, I think.

First test JUMBO with a Java interpreter (if you don't have scene1.sgm, use any simple WF-XML file, without internal subset or CDATA):

java jumbo.sgml.Jumbo scene1.sgm

This should bring up the JUMBO browser, read scene1.sgm, parse and convert it into a tree and display this in the TOC. If successful the root node should shown (#DOCROOT). To expand the tree click on the folder icon. If this has failed, System.out may give hints. Further indications of success are viable trees under "Show ElementTypes", "Show MIMETypes", "Show XML" and "Show Config". No further documentation is given for the alpha release. Description of functions and further examples will be given in the beta.

You should now download one or more of the SAX compliant parsers and the SAX Driver interface. All the instructions are given at http://www.microstar.com/xml/sax which also has links to the home pages for the other parsers. I will assume Lark. Edit the classpath to look like:

set classpath=C:\mydir\demos;C:\lark10;C:\lfred\sax

where
C:\lark10 contains textuality\lark and
C:\lfred\sax contains com\microstar\sax and org\xml\sax

(On UNIX the slashes go the other way :-).

Before testing Jumbo you should test the SAX/parser interface works. DavidM describes how; the command looks like:

java SAXDemo com.microstar.sax.LarkDriver scene1.sgm

If you have problems here, they are almost certainly in your CLASSPATH and are JUMBO-independent.

Now run the GUI-independent test of JUMBO/SAX/*Driver. Make sure that you have a file jumbo/config.xml which is accessed through the classpath. This contains an XML-based association of parserName with parserDriver class. (I anticipate that config.xml will be an essential part of Jumbo - suggestions on names, locations and content will be welcome). Issue the command:

java jumbo.sgml.JumboSAX Lark scene1.sgm

This should load the LarkDriver (com.microstar.sax.LarkDriver) by resolving its name from the config.xml.The result should be initially similar to the last test, but finish with JUMBO's internal representation of a parsed input stream (ESIS-like).

Finally run the full JUMBO GUI. This can load different parsers at the commandline, or from the menu. (The latter do not yet use SAX and are earlier hardcoded versions. I hope to use config.xml to generate the menu in the beta.) The commandline is:

java jumbo.sgml.Jumbo scene1.sgm PARSER=SAX:Lark

This should generate a display very similar to the first run of JUMBO. If so you have now reached the same stage of debugging that I am at :-)

BUGS:

There will be bugs at this stage :-) Beside the many JUMBO bugs there may also be a few bugs:

in the parsers (including differences of opinion on how to interpret the spec). I know of about 3.
in the *Driver classes from DavidM (2-3 known bugs at 1998-01-26; David has fixed them)
in JumboSAX (cf SAXDemo)

For this reason you should always look to the SAX home page for the latest versions of the first two. JumboSAX.java is included in case there are problems at that level.

JUMBO-HTML

JUMBO can be extended by adding class libraries on a per-element basis. This is normally done in packages, so jumbo.sgml.html supports HTML. Mapping the elements to the classes is done in the following way:

A schema.xml file is provided at the same level as the class libaries. Thus /mydir/demos/jumbo/sgml/html/schema.xml relates to the package jumbo.sgml.html
Each element for which semantics are provided has an entry in schema.xml of the form:

<CLASS NAME="TT">
<JAVA>jumbo.sgml.html.TextNode</JAVA>
</CLASS>
which maps TT onto the TextNode class. Since several nodes use this, it is a simple form of inheritance.

Elements can invoke methods in the mapped class (e.g. through button-clicks, tree traversals, document-driven).
The appropriate schema in the document is identified by the namespace prefix. Thus:

<?xml:namespace href="jumbo/sgml/html/schema.xml" as="HTML"?>
will map all elements of the form <HTML:TT> onto the name TT and hence to TextNode.class.

Where there is no namespace prefix, the reserved (JUMBO) keyword "#DEFAULT" will map elements onto the namespace.

JUMBO support classes

Besides the core support in jumbo.sgml, there are three support classes:

jumbo.util; a few routines not provided in java.* or modified to my programming style.
jumbo.euclid; numerical and geometrical routines.
jumbo.simplegraph; graphical support routines, especially GKS-like 2D scaling routines.