Chapter 8 Help System

This chapter describes the Help system in the Java Desktop System.

Introduction to the Help System

The source documents for the online Help in the Java Desktop System are XML files. The XML files are written to the DocBook XML Version 4.1.2 document type definition (DTD). The DocBook XML files are converted to HTML, and the HTML is displayed in the Help browser. For more information about DocBook XML, see the following URL:

http://www.oasis-open.org/docbook/xml

The Java Desktop System can display Help in two Help browsers, as follows:

• JDSHelp

• Yelp

JDSHelp Browser

The JDSHelp browser is based on the Javahelp browser. For more information about Javahelp file formats, how to write documents for Javahelp, and how to group documents in hierarchies, see the following URL:

http://java.sun.com/products/javahelp/reference/docs/index.html

Yelp Browser

The Yelp browser uses Open Source Metadata Framework (OMF) files, and a cataloging system.

OMF Files

The XML file for each manual has an associated OMF file. The OMF file contains information about the manual that is used by the Yelp browser. OMF files have a .omf extension.

When you install an application, the installation process installs an OMF file to a directory of OMF files. If a Help document has an associated OMF file in an OMF file directory, users can access the Help document from the Yelp browser.

OMF files contain information about Help documents such as the following:

• The location of the XML file for the Help document

• The title of the Help document

• A subject category to which the Help document belongs

ScrollKeeper Cataloging System

ScrollKeeper is a cataloging system for documentation. The Yelp Help browser uses ScrollKeeper to catalog the manuals on the system. ScrollKeeper manages the information in the OMF files for the Yelp Help browser.

ScrollKeeper uses the information in the OMF files to enable the Yelp Help browser to find Help documents on a system. When you install an application, the installation process installs an OMF file to a directory of OMF files.

ScrollKeeper builds a table of contents for each Help document that has an associated OMF file. ScrollKeeper builds the table of contents from the XML file specified in the OMF file. The table of contents for the Help document is displayed in the left pane of the Yelp Help browser window, and enables users to navigate the Help document in the left pane. The title of the document in the OMF file is also displayed in the left pane of the Yelp Help browser window.

ScrollKeeper contains a hierarchy of subject categories to which a Help document can belong. The Help documents are organized into this hierarchy of subject categories in the left pane of the Yelp Help browser window. The subject category of the document in the OMF file determines the location of the document in the hierarchy. The hierarchy of subject categories is defined in the following file:

/usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml

The subject category of a document must correspond to a subject category in the following file:

/usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml

If the Help document XML file is moved to a new location, then you might need to update the location in the OMF file.