© 2000 Kevin Lewis All rights reserved. Presented By: Kevin Lewis Creating a JavaHelp System Start

© 2000 Kevin LewisAll rights reserved.

Presented By:

Kevin Lewiswww.kevinlewis.com

Creating a JavaHelp System

Start


Contents

What is JavaHelp? What you need

Demo Components of a JavaHelp system

How they work together Directory and file organization XML and JavaHelp Topic, data, and navigation files

JavaHelp system enhancements Secondary windows Pop-up windows Custom lightweight components Merging HelpSets

Contents

Demo

Presenting a JavaHelp System

Help-Authoring Tools

Closing Thoughts

Components of a JavaHelp System

JavaHelp System Enhancements

What is JavaHelp?


Contents

Presenting a JavaHelp system Standalone Context-sensitive Embedded

Help-authoring tools RoboHELP

Closing thoughts Future of JavaHelp Survey information More information

Questions & answers

Contents

Demo



Closing Thoughts



What is JavaHelp?


What is JavaHelp?

Online help system written in Java Platform independent Best for Java-based interfaces

Topic files based on HTML Data and navigation files based on XML Installation options

Local application Network application Java applet Java product suite

Contents

What is JavaHelp?

Demo



Closing Thoughts




JavaHelp download http://www.java.sun.com/products/javahelp

Java runtime environment (JRE) JDK 1.1 or, preferably, Java SDK 1.2 or

higher Version 1.1 with JDK 1.1 requires Swing 1.1

or higher Optional help-authoring tool Java developer

What You Need

What is JavaHelp?

Contents

Demo



Closing Thoughts




Demo

System uses standard tripane window

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Toolbar

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Navigation pane

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Content pane: uses standard HTML

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

‘File’ menu offers standard ‘Open’ (for opening other HelpSets) and ‘Exit’ menu items

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

‘Options’ menu offers option for changing the font in the navigation pane

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

•Standard previous and next buttons function like in a Web browser—not in a predefined order

•Print buttons for setting up your printer and printing the current topic

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Tabs for switching between TOC, index, and word-search index

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

•Standard TOC with expandable and collapsible categories

•Categories and/or topics can link to topics

•Synchronized

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

•Standard index with primary and secondary index terms

•Find feature for user to type word to search for in index

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

•Word-search index for user to search contents of all help topics for word or phrase

•Search results are listed by topic title in order of likely match

•Circle shows how close the match is

•Number indicates how many times the search term is found in that topic

•System displays #1 topic and highlights the search term

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Show and hide buttons for showing and hiding the navigation pane

Demo

Contents

What is JavaHelp?



Closing Thoughts




Demo

Invoke secondary and pop-up windows using links in text, buttons, or images

Demo

Contents

What is JavaHelp?



Closing Thoughts





Topic files (HTML) Data files

HelpSet file (XML) Map file (XML)

Navigation files TOC (XML) Index (XML) Word search index

HelpSet Viewer


Contents

What is JavaHelp?



Closing Thoughts


Demo


How the Components Work Together


Contents

What is JavaHelp?



Closing Thoughts


Demo


Directory and File Organization

TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp

Standard directory and file structure for a JavaHelp system


Contents

What is JavaHelp?



Closing Thoughts


Demo



TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp

HelpSet data and navigation files at top level of project folder


Contents

What is JavaHelp?



Closing Thoughts


Demo



TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp

Directory that you create when

generating the word-search index


Contents

What is JavaHelp?



Closing Thoughts


Demo



TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp

Contains image files for images used in

topic files as well as navigation system


Contents

What is JavaHelp?



Closing Thoughts


Demo



TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp

Contains HTML topic files and other subdirectories—subdirectory structure is

easy to manage if you copy the structure of your TOC


Contents

What is JavaHelp?



Closing Thoughts


Demo



TypeFacerHelp

JavaHelpSearch

HelpSet.hs

Map.jhm

TOC.xml

Index.xml

Images

Topics

FieldLevelHelp Contains HTML files for field-level help topics


Contents

What is JavaHelp?



Closing Thoughts


Demo


Topic Files

HTML-based Use hyperlinks and other standard HTML

components Employ lightweight components

Standard JavaHelp components “Home-grown” components

See JavaHelp documentation for limitations


Contents

What is JavaHelp?



Closing Thoughts


Demo


XML and JavaHelp

JavaHelp files are XML-based HelpSet Map TOC Index

HelpSet Viewer uses DTDs for each JavaHelp file


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File

XML-based “Master control” file in system System reads this file first HelpSet data elements

Title of help system Location of map file Default help topic on startup

Navigation elements Internal information Tool tip labels Name and location of navigation files Delete or rearrange order for the same

appearance in the viewer’s navigation pane


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File

<?xml version='1.0' encoding='ISO-8859-1' ?>

<!DOCTYPE helpset

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"

"http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<helpset version="1.0">

</helpset>

… HelpSet Data Elements

… Navigation Elements

Uses the <helpset> tag to nest all of the information


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File

HelpSet Data Elements

<title>Typeface Tester Online Help</title>

<maps>

<mapref location="Map.jhm"/>

<homeID>overview</homeID>

</maps>

Specifies the title of the help system


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File

HelpSet Data Elements

<title>Typeface Tester Online Help</title>

<maps>

<mapref location="Map.jhm"/>

<homeID>overview</homeID>

</maps>

Location and name of map file and the map ID of the default help topic


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File

Navigation Elements<view>

<label>TypeFacer TOC</label>

<name>TOC</name>

<type>javax.help.TOCView</type>

<data>TOC.xml</data>

</view>

Text for the tool tip


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File



<name>TOC</name>



</view>

Internal information


Contents

What is JavaHelp?



Closing Thoughts


Demo


HelpSet File



<name>TOC</name>



</view> Location and name of file containing navigation data


Contents

What is JavaHelp?



Closing Thoughts


Demo


Map File

XML-based Assigns URLs to map IDs (shorter

“nicknames”) Map topic files and image files used in

navigation controls or lightweight components

Use IDs instead of full URL HelpSet and navigation files Topic files for secondary windows


Contents

What is JavaHelp?



Closing Thoughts


Demo


Map File


<!DOCTYPE map

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"

"http://java.sun.com/products/javahelp/map_1_0.dtd">

<map version="1.0">

</map>

… Map IDs with corresponding URLs

Uses the <map> tag to nest all of the information


Contents

What is JavaHelp?



Closing Thoughts


Demo


Map File



<mapID target="toplevelfolder“ url="images/toplevel.gif" />



<mapID target="overview" url="topics/overview.htm" />

<mapID target="colors" url="topics/colors_view.htm" />

I use optional comments to identify different sections in the map file


Contents

What is JavaHelp?



Closing Thoughts


Demo


Map File



<mapID target="toplevelfolder“ url="images/toplevel.gif" />



<mapID target="overview" url="topics/overview.htm" />

<mapID target="colors" url="topics/colors_view.htm" />

Map ID Corresponding URL


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC

TOC file in HelpSet XML-based Uses map IDs to map top level, category, and

topic titles to topic files TOC file dictates structure of TOC in help

system Nest items to create top level, category, and

topic levels

TOC component in help system Traditional online help TOC Uses default top level, category, and topic icons

or custom icons for each Synchronized


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


<!DOCTYPE toc

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"

"http://java.sun.com/products/javahelp/toc_1_0.dtd">

<toc version="1.0">

</toc>

… TOC structure for top level, categories, and topics

Uses the <toc> tag to nest all of the information


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC

<tocitem image="toplevelfolder" text="Typeface Tester Online Help">

<tocitem image="topic" target="overview" text="Overview"/>

<tocitem image="topic" target="typefaces" text="Typeface View"/>

<tocitem image="topic" target="colors" text="Color View"/>

<tocitem image="topic" target="online_help" text="Online Help"/>

<tocitem image="category" text="How to">

<tocitem image="topic" target="switch_views" text="Switch Views"/>

<tocitem image="topic" target="enter_text" text="Enter Text"/>

<tocitem image="topic" target="clear_text" text="Clear Text"/>

<tocitem image="topic" target="change_fonts" text="Change Fonts"/>

<tocitem image="topic" target="text_styles" text="Apply Text Styles"/>

<tocitem image="topic" target="apply_colors" text="Apply Colors"/>

</tocitem>

</tocitem> Notice the nests and the hierarchy for top level, category, and topics


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC

The TOC file yields this TOC in the help system


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


First item in the nest creates the top level


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


Map ID of the image to display with the corresponding line in the TOC


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


The top level text to display on the corresponding line in the TOC


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC





Series of TOC items yields those lines in the TOC


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC





Map ID for the topic icon —if you don’t specify an image,

JavaHelp uses its own default


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC





The topic title to display on the corresponding line in the TOC


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC





The map ID of the topic file to display

when the user selects that topic


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


<tocitem image="topic" target="switch_views" text="Switch Views"/> <tocitem image="topic" target="enter_text" text="Enter Text"/> <tocitem image="topic" target="clear_text" text="Clear Text"/> <tocitem image="topic" target="change_fonts" text="Change Fonts"/> <tocitem image="topic" target="text_styles" text="Apply Text Styles"/> <tocitem image="topic" target="apply_colors" text="Apply Colors"/>

</tocitem>

Notice that the nest creates a category

with topics


Contents

What is JavaHelp?



Closing Thoughts


Demo


TOC


<tocitem image="topic" target="switch_views" text="Switch Views"/> <tocitem image="topic" target="enter_text" text="Enter Text"/> <tocitem image="topic" target="clear_text" text="Clear Text"/> <tocitem image="topic" target="change_fonts" text="Change Fonts"/> <tocitem image="topic" target="text_styles" text="Apply Text Styles"/> <tocitem image="topic" target="apply_colors" text="Apply Colors"/>

</tocitem>

Map ID for the category icon —if you don’t specify an image,

JavaHelp uses its own default


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index

Index file in HelpSet XML-based Uses map IDs to map index terms to topic files Index file dictates structure of index in help

system Must manually alphabetize index terms Nest items to create primary and secondary

index terms Must manually produced “see” or “see also”

terms

Index component in help system Traditional online help index Feature to type keyword to search the index


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index


<!DOCTYPE index

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"

"http://java.sun.com/products/javahelp/index_1_0.dtd">

<index version="1.0">

</index>

… Index structure for index terms

Uses the <index> tag to nest all of the information


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index

<indexitem target="overview" text="overview"/>

<indexitem target="switch_views" text="switching views"/>

<indexitem text="text">

<indexitem target="text_styles" text="bolding"/>

<indexitem target="clear_text" text="clearing"/>

<indexitem target="apply_colors" text="colors, applying"/>

<indexitem target="enter_text" text="entering"/>

<indexitem target="change_fonts" text="fonts, changing"/>

<indexitem target="text_styles" text="italicizing"/>

</indexitem>

<indexitem target="typefaces" text="Typeface View"/>

Notice the nest to specify primary and secondary index terms


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index

Partial index from the index file


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index









</indexitem>

The index term to display on the

corresponding line in the index


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index









</indexitem>

The map ID of the topic file to display

when the user selects that index item


Contents

What is JavaHelp?



Closing Thoughts


Demo


Index

Notice that the nest creates primary and

secondary index terms









</indexitem>


Contents

What is JavaHelp?



Closing Thoughts


Demo


Word Search Index

Word-search index files Create with the jhindexer command that accompanies

JavaHelp Results in a set of files within one ‘JavaHelpSearch’

directory, which you include with your delivered files Uses stopwords to eliminate common words such as

“a” or “the”

Word-search index component in help system User enters a “natural language query”—similar to

conducting a search through a Web site’s search engine

Help system searches database in the ‘JavaHelpSearch’ folder


Contents

What is JavaHelp?



Closing Thoughts


Demo


Word Search Index

1. To build word-search index, start with all help topics under one master ‘Topics’ directory in your master project file One reason to follow my recommendations for directory

and file structure

2. At a command prompt, make the project directory (the one immediately above the ‘Topics’ directory) the active directory

3. Run the jhindexer command against the ‘Topics’ directory C:\jh1.1\javahelp\bin\jhindexer Topics (Windows) /jh1.1/javahelp/bin/jhindexer Topics (Unix)

4. Run the help system and try it out


Contents

What is JavaHelp?



Closing Thoughts


Demo



Secondary windows Pop-up windows Other lightweight components Merging HelpSets

Contents

What is JavaHelp?



Closing Thoughts

Demo




Secondary and Pop-Up Windows

Use lightweight components Implemented in the topic file as an object Invoked with buttons, images, or textComponents of a

JavaHelp System




Closing Thoughts

Contents

What is JavaHelp?

Demo



Both programmed the same but function differently A pop-up always appears adjacent to the link

that invokes it, but you can specify where a secondary window appears

Users can’t adjust or move a pop-up, but they can minimize, maximize, resize, and move a secondary window

A pop-up does not have a title bar—it just contains text, but a secondary window has a title bar

A pop-up closes automatically when the user clicks another area in the viewer, but the user must manually close a secondary window





Closing Thoughts

Contents

What is JavaHelp?

Demo



<object CLASSID="java:com.sun.java.help.impl.JHSecondaryViewer">

<param name="id" value="pop.jhtoc">

<param name="viewerActivator" value="javax.help.LinkButton">

<param name="viewerStyle" value="javax.help.Popup">

<param name="viewerSize" value="325,150">

<param name="text" value="JavaHelp Note">

<param name="textColor" value="red">

<param name="textFontSize" value="medium">

<param name="textFontWeight" value="plain">

</object>

The code, embedded in the topic’s HTML

file, produces a button that invokes

a popup window





Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>

The ‘CLASSID’ is the same for both secondary and

popup windows Components of a JavaHelp System




Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>

The ‘id’ parameter specifies the map ID for the topic file containing the text to display in the window

The text in this popup window comes from the file assigned

to the map ID ‘pop.jhtoc’





Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>

The ‘viewerActivator’ parameter specifies which mechanism is used to invoke the

window: text, image, or button

The system uses a button to invoke the popup window





Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>

The ‘viewerStyle’ parameter specifies whether to open a popup

window or a secondary window

The window invoked is a popup window





Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>

The ‘viewerSize’ parameter specifies the size of the window in pixels

The popup window is 325 pixels wide and 150 pixels tall





Closing Thoughts

Contents

What is JavaHelp?

Demo












</object>The ‘text’ parameters specify the

text to display on a button, the text color, font size, and font weight

The text in this button says ‘JavaHelp Note’, is red, is of medium size, and has a plain

weight (as opposed to bold)





Closing Thoughts

Contents

What is JavaHelp?

Demo


Custom Lightweight Components

Multimedia Related topics Whatever you createComponents of a

JavaHelp System




Closing Thoughts

Contents

What is JavaHelp?

Demo


Merging HelpSets

Two ways to merge HelpSets Dynamically, through programming using the

JavaHelp API Statically, through the HelpSet file

Static merging uses the <subhelpset> tag to specify a secondary HelpSet to merge with the master HelpSet

Can use an optional “dataless” HelpSet TOCs, indexes, and word-search indexes

merge in same components





Closing Thoughts

Contents

What is JavaHelp?

Demo


Merging HelpSets

<subhelpset location=“../OtherProject/HelpSet.hs” />

<subhelpset location=“../ThirdProject/HelpSet.hs” />

In the master HelpSet file, specify the relative URL(s) to the secondary HelpSet file(s)





Closing Thoughts

Contents

What is JavaHelp?

Demo



Application without help Standalone help Context-sensitive help

Screen-level Field-level

Embedded helpPresenting a JavaHelp System



Contents

What is JavaHelp?

Demo


Closing Thoughts


Application Without Help

F1 does notactivate help

system




Contents

What is JavaHelp?

Demo


Closing Thoughts



No ‘Help’ menu




Contents

What is JavaHelp?

Demo


Closing Thoughts



No ‘Help' button




Contents

What is JavaHelp?

Demo


Closing Thoughts


Standalone Help System

F1, ‘Contents’ menu item, and ‘Help’ button all launchsame standalone help system




Contents

What is JavaHelp?

Demo


Closing Thoughts


Context-Sensitive Help: Screen-Level

‘Contents’ menu item launchesdefault standalone help system




Contents

What is JavaHelp?

Demo


Closing Thoughts


Context-Sensitive Help: Screen-Level

F1, ‘For This Screen’ menu item, and ‘Help’ button launches

CSH for current screen




Contents

What is JavaHelp?

Demo


Closing Thoughts


Context-Sensitive Help: Field-Level

First click field-level help button and then a control—system displays help for that control




Contents

What is JavaHelp?

Demo


Closing Thoughts


Embedded Help

Good practice to provide mechanism for hiding embedded help




Contents

What is JavaHelp?

Demo


Closing Thoughts



Major vendors provide JavaHelp support eHelp RoboHELP ForeFront ForeHTML WexTech Doc-to-Help Visit Sun’s JavaHelp Web page for complete list

http://java.sun.com/products/javahelp/industry.html

Make process easier and faster Less room for error Best if you have strong knowledge of both

the HAT and JavaHelp so that you can better customize your JavaHelp system

Should still understand JavaHelp without HAT in case you must troubleshoot problems





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP HTML provides single source for developing Web-based systems: Sun Microsystems JavaHelp Oracle Help for Java Microsoft HTML Help eHelp WebHelp

Get more product information at eHelp’s Web site http://www.ehelp.com





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

When creating new projects, RoboHELP provides a wizard to specify information you would

otherwise manually enter in HelpSet data files





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

A common interface enables the user to work on both data files and topic files without switching to different screens





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP has a related topics feature that embeds its own lightweight component into the help topic to implement a related topics control





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP has an auto-generate TOC feature, but it typically requires

modification to get what you want





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP’s Smart Index Wizard automatically creates indexes (including the primary and

secondary index terms) and is good in a pinch, but it requires a lot of modification to create a solid

index





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

Generating a the final help system is easy, and you can select different types of help platforms (such as

HTML Help or Web Help)—this illustration shows that I chose a JavaHelp system





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

One of my favorite features during the JavaHelp system generation is a pop-up box

that reminds the user of JavaHelp’s limitations





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP handles displaying the help system so that you don’t have to manually run the HelpSet Viewer





Contents

What is JavaHelp?

Demo

Closing Thoughts


RoboHELP

RoboHELP’s finished system would require a bit of modification to match the system I

created manually—but it certainly makes the development process much less painful and

offers a few great enhancements





Contents

What is JavaHelp?

Demo

Closing Thoughts


Future of JavaHelp

Version 1.1.1 is the latest Future versions unknown Viewer module (JEditorPane) is being

improved Java SDK 1.4 will contain important

performance improvements More efficient memory usage Added HTML 4 tags Bug fixes

Serious investigation about adding an XML editor kit

Need (or no need) for JavaHelp?


Closing Thoughts




Contents

What is JavaHelp?

Demo


Closing Thoughts

WinWriters survey JavaHelp authors’ experience levels

1% could write a book on it 5% used it frequently in several projects 17% experimented or used it a bit 31% read or heard about it 45% had no experience

Help authors’ views on JavaHelp’s importance 4% found it invaluable, a core component 6% found it very important to their projects 9% found it useful, but could get along without it 11% used it very little in their projects 69% had no need for it


Closing Thoughts




Contents

What is JavaHelp?

Demo


More Information

JavaHelp Web site http://java.sun.com/products/javahelp/

JavaHelp list archives http://archives.java.sun.com/archives/javahelp-

interest.html

“Creating Effective JavaHelp” http://www.oreilly.com/catalog/creatingjavahelp/

These slides maintained on the Web http://www.kevinlewis.com


Closing Thoughts




Contents

What is JavaHelp?

Demo

Documents

© 2000 Kevin Lewis All rights reserved. Presented By: Kevin Lewis Creating a JavaHelp System Start