Jacob Help


Chr. Clemens Lee
 
2000-11-19


Abstract

This document describes the usage of Java Help for Jacob.

Warning: most links in this document work only on my development machine. I will think about a structure that is more transferable to the web and user installations in the future.

Table of Contents

1   Java Help
2   Map.jhm
3   Errors.html
    3.1   Gnudoit failed!
Links

1   Java Help

The java help programmers documentation is locally stored here. So far Java Help has been used only to add document browsing capability to Jacob.

Java Help is invoked from the menu system by default in the class ../../ccl/src/ccl/swing/MainJMenuBar.java. The standard Java Help documentation for this standard use is here.

2   Map.jhm

The Map.jhm file is used to specify help ids which are used to specify urls inside html help files.
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!--DOCTYPE map
  PUBLIC "-//Sun Microsystems Inc.//DTD Map Version 1.0//EN"
         "http://java.sun.com/products/javahelp/map_1_0.dtd"-->
<map version="1.0">
    <mapID target="index" url="index.html" />
</map>

3   Errors.html

Instead of showing a dialog with an error message in some cases we want to show an error message with html so that the user has the ability to continue browsing in the documentation (e.g. faq) to find a solution for the problem. For this purpose there is one html page which contains these error messages. Then we use Java Help to present and jump to the right message.
<html>
<head>
   <TITLE>Jacob Error Messages</TITLE>
</head>
<BODY TEXT="#000000" BGCOLOR="#D3DCE2" LINK="#4367AB" VLINK="#551A8B" ALINK="#FF0000">
&nbsp;
<CENTER>
<H1>
Jacob Error Messages</H1></CENTER>
&nbsp;
<p>
<P><BR>Back to <A HREF="index.html">Jacob's main page</A>
<BR>
<HR WIDTH="100%"><A HREF="http://www.kclee.com/clemens/">Chr.
Clemens Lee</A>, email to: <A HREF="mailto:clemens@kclee.com">clemens@kclee.com</A>
</BODY>
</HTML>

But we have a problem. If one message in html is smaller than a full user screen (and this is very likely) the user might not even know which error happened. So how can we make 100% sure the user realizes that an error happened? One way would be to have enough empty lines above and below every error message. Then the user sees always only one error message and should never get confused.

Bumm. Unfortunately Java Help seems to be very instable, especially when a long page with anchors is used.

3.1   Gnudoit failed!

This error message is raised when gnudoit was not executed successfully.
<html>
<head>
   <TITLE>Jacob Error Message: Gnudoit</TITLE>
</head>
<BODY TEXT="#000000" BGCOLOR="#D3DCE2" LINK="#4367AB" VLINK="#551A8B" ALINK="#FF0000">
&nbsp;
<CENTER>
<H1>
Jacob Error Message: Gnudoit</H1></CENTER>
&nbsp;
<p>
<h2>Error: Gnudoit failed!</h2><p>

The gnudoit helper application did not execute properly.
Maybe it is not installed correctly together with the Emacs editor.
You can find the installing documentation of the gnuserv package for the ntemacs at:
<a href="http://www.cs.washington.edu/homes/voelker/ntemacs.html#assoc">http://www.cs.washington.edu/homes/voelker/ntemacs.html#assoc</a><p>

For additional information you can look at the 
<a href="index.html#installation_gnuserv">Jacob gnuserv installation</a>
section or read the <a href="tutorial.html#1.9">Jacob FAQ</a> which has further comments
about this problem.

<P><BR>Back to <A HREF="index.html">Jacob's main page</A>
<BR>
<HR WIDTH="100%"><A HREF="http://www.kclee.com/clemens/">Chr.
Clemens Lee</A>, email to: <A HREF="mailto:clemens@kclee.com">clemens@kclee.com</A>
</BODY>
</HTML>
This error message must have a help id in the Map.jhm file.
    <mapID target="error_gnudoit" url="ErrorGnudoit.html" />
The invocation of the help viewer happens in jacob.EmacsEditor in the method '_showGnudoitErrorMessage'.

Links

Programming with the Java Help System:  /usr/local/java/jh1.1/doc/jhug/dev/dev.html
Errors.html:  Errors.html
jacob.EmacsEditor:  ../src/jacob/EmacsEditor.java
Clemens' Java Page:  http://www.kclee.com/clemens/java/
Clemens' Home Page:  http://www.kclee.com/clemens/


clemens@kclee.com,    last revised:   $date: $