Создание HelpSet с помощью программы JavaHelp(tm)

Добавлено : 23 Dec 2008, 16:46

Содержание

1 Введение
2 Пример для демонстрации
3 Индексный файл и файл содержания
4 Проверка результата
5 Ссылки

Введение

Программа JavaHelp дает вам возможность добавить систему оперативной помощи к любой системе с Java Runtime Environment (JRE). При помощи JavaHelp вы можете встроить оперативную документацию в ваши клиентские программы. Это можно сделать для апплетов и приложений. Кроме того, можно использовать JavaHelp либо с компонентами JavaBeans(tm), либо в качестве автономной системы помощи для сторонних систем.

Начать работу с JavaHelp легко. Просто зайдите на страницу http://java.sun.com/products/javahelp/download_binary.html. Вы можете загрузить либо пользовательскую версию с JRE, либо версию, ориентированную на разработчиков (в виде Zip-архива или самораспаковывающейся программы). В загрузочном пакете находится также "Руководство пользователя по JavaHelp". Просматривая это руководство, вы увидите систему JavaHelp в действии.

После запуска основанной на Swing системы помощи для JavaHelp на экране отображается информация в нескольких областях просмотра. Среди этих областей - содержание, индекс тем и система поиска. Эти три системы вместе называются HelpSet и могут включать в себя несколько файлов тем. Естественно, работа по созданию файлов тем помощи и навигационных файлов, связывание темы помощи с файлом, содержащим необходимую информацию, остается за вами. Файлы тем имеют формат HTML, а навигационные файлы форматируются в XML. Хотя вы можете использовать программные средства сторонних производителей для автоматизации создания необходимых файлов. Например, программа RoboHELP генерирует необходимые файлы в формате JavaHelp. Список программ, поддерживающих формат программы JavaHelp, находится на странице http://java.sun.com/products/javahelp/industry.html.

Пример для демонстрации

Для демонстрации системы JavaHelp в действии давайте создадим HelpSet "Hello, JavaHelp". Для этого необходимо настроить специальную схему каталогов. Это поможет не смешивать файлы HelpSet с другими. Навигационные файлы располагаются в каталоге верхнего уровня, а файлы тем и изображений - в подкаталогах.

Сначала создайте каталог с именем help. В нем создайте каталог Hello.

В каталоге Hello создайте подкаталоги для хранения реальных файлов помощи. Для демонстрации "Hello, JavaHelp" создайте один каталог First и второй - Last.

После создания структуры каталогов можно начать создание навигационных файлов и файлов помощи. Структура каталогов выглядит так:

+ help
  + Hello
    + First
    + Last

DTD для главного файла HelpSet находится на странице http://java.sun.com/products/javahelp/helpset_1_0.dtd. В этом файле создаются записи для элементов карты, а также оглавление и индекс. Нет ничего сложного в названиях файлов. Необходимо только, чтобы файл HelpSet заканчивался расширением .hs. Ниже приведен в качестве примера файл HelpSet - hello.hs; карта находится в файле Map.jhm, содержание - в toc.xml, а индекс - в index.xml. Создайте файл hello.hs в каталоге help.

<?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">
  <title>Hello, JavaHelp</title>
  <maps>
    <mapref location="Map.jhm"/>
    <homeID>overview</homeID>
  </maps>
  <view>
    <name>TOC</name>
    <label>TOC</label>
    <type>javax.help.TOCView</type>
    <data>toc.xml</data>
  </view>
  <view>
    <name>Index</name>
    <label>Index</label>
    <type>javax.help.IndexView</type>
    <data>index.xml</data>
  </view>
</helpset>

Для файла карты необходимо создать отображение ID на файлы, например, следующим образом:

<mapID target="one" url="Hello/First/one.htm" />

Проверьте, что месторасположение файлов помощи задано относительно HelpSet. Вы можете жестко запрограммировать полные пути, но как только вы переместите JAR, все пути станут неправильными. Естественно, эти пути могут быть полными URL на ресурсы в Web. Если вы имеете один файл помощи в основном каталоге (overview.htm) и по два файла помощи в каждом из каталогов First и Least, ваш XML-файл карты отображения может выглядеть следующим образом. Создайте этот файл Map.jhm в основном каталоге.

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!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">
  <mapID target="overview" url="Hello/overview.htm" />
  <mapID target="one" url="Hello/First/one.htm" />
  <mapID target="two" url="Hello/First/two.htm" />
  <mapID target="three" url="Hello/Last/three.htm" />
  <mapID target="four" url="Hello/Last/four.htm" />
</map>

Индексный файл и файл содержания

Теперь о файле содержания и индексном файле. Они обеспечивают альтернативное средство работы с различными файлами помощи. Они также описываются в XML-файлах.

Для файла содержания каждое задание из карты отображается в текст, появляющийся в содержании. Создайте следующий файл toc.xml в основном каталоге.

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!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">
<tocitem image="toplevelfolder" target="overview" text="Hello, JavaHelp">
    <tocitem text="First Stuff">
      <tocitem target="one" text="The One"/>
      <tocitem target="two" text="The Second"/>
    </tocitem>
    <tocitem text="Last Stuff">
      <tocitem target="three" text="What's Third?"/>
      <tocitem target="four" text="The End"/>
    </tocitem>
</tocitem>
</toc>

Индекс - это еще один способ представления данных. При создании файла index.xml вы должны упорядочить термины в той последовательности, в которой хотите их отобразить. Просто создайте XML-файл с набором иерархических элементов <indexitem>. В каждом элементе <indexitem> запишите значение атрибута текста и значение атрибута задания. Значение атрибута для текста указывает, что отображается для пользователя в индексе. Значение атрибута задания указывает, какой раздел помощи отобразить. Создайте в основном каталоге следующий файл index.xml.

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!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">
  <indexitem text="The First?">
    <indexitem target="one" text="I'm One"/>
    <indexitem target="two" text="I'm Second"/>
  </indexitem>
  <indexitem text="The Last?">
    <indexitem target="three" text="We're Third!"/>
    <indexitem target="four" text="We're Last"/>
  </indexitem>
  <indexitem target="overview" text="Overview!!!"/>
</index>

В файле карты отображения упоминается пять HTML-файлов:

Hello/overview.htm
Hello/First/one.htm
Hello/First/two.htm
Hello/Last/three.htm
Hello/Last/four.htm

Следовательно, вы должны создать их. Создайте эти файлы в соответствующих подкаталогах или каталоге Hello. Попробуйте создать файлы с какой-либо интересной информацией, например, запишите несколько предложений обзорной информации в файле overview.htm. Полная структура каталога теперь будет выглядеть следующим образом:

+ help
  hello.hs
  index.xml
  Map.jhm
  toc.xml
  + Hello
    overview.htm
    + First
      one.htm
      two.htm
    + Last
      three.htm
      four.htm

Проверка результата

Для проверки правильности проделанных действий запустите программу hsviewer, поставляющуюся с JavaHelp, и загрузите файл hello.hs. Программа hsviewer находится в подкаталоге demos/bin (Unix) или demos\bin (Windows) каталога с установленным пакетом JavaHelp. Например, в Unix перейдите в подкаталог demos/bin и введите:

hsviewer -helpset hello.hs -classpath path

Замените "path" на путь к hello.hs HelpSet.

После запуска hsviewer нажмите на кнопку Browse и найдите файл hello.hs. Затем нажмите на кнопку Display для активизации файла помощи. Поскольку hello.hs содержит два тега <view>, вы обнаружите две закладки с левой стороны: одна для содержания, вторая для индекса. В правой части отобразится HTML-файл, соответствующий выбранному слева элементу.

Вы можете также добавить закладку поиска. Для этого запустите программу jhindexer и добавьте еще один элемент <view> в HelpSet. Введите следующую команду jhindexer в каталоге с файлом hello.hs.

jhindexer Hello

Если команда отсутствует в вашей переменной path, необходимо ввести полный путь к jhindexer. Эта программа находится в подкаталоге javahelp/bin (Unix) или javahelp\bin (Windows) вашего каталога с установленным пакетом JavaHelp.

Ниже приведен тег <view>, который вы должны добавить в hello.hs. JavaHelpSearch - это имя каталога, используемого для сохраняемых вспомогательных файлов индекса.

<view>
    <name>Search</name>
    <label>Word Search</label>
    <type>javax.help.SearchView</type>
    <data engine="com.sun.java.help.search.DefaultSearchEngine">
        JavaHelpSearch
    </data>
</view>

Ссылки

Дополнительная информация о сравнении с шаблоном и регулярных выражениях находится в статье "Регулярные выражения и язык программирования Java" (http://java.sun.com/jdc/technicalArticles/releases/1.4regex/).

Теги: javahelp