JavaHelpジェネレータ(JHG) Ver 0.5 2008/3/18

JavaHelpジェネレータ(JHG)をGPLにてリリースしました。開発者向けのソフトウェアツールです。商品スタッフIIのヘルプファイル作成に利用しています。

本ソフトウェア及びドキュメントはGNU General Public Licenseにてライセンスされます。
著作権者は有限会社クリプトメディアです。

ダウンロード jhg-0.5.zip (Javaソースコードのみ。バイナリはありません)

本ソフトウェアの目的

JavaHelpを簡単に作成するためのツールです。一般に、JavaHelpを作成するには、（特別なオーサリングソフトを使わない限り）ヘルプセット、マップファイル、インデックスファイルなどを手書きで記述しなければなりませんが、これは極めて退屈な作業で間違いも発生しやすいと思われます。

JHGは、ある「取り決め」を前提として、これらのファイルを自動生成します。JavaHelpのコンテンツはHTML3.2のファイル（及び画像などの任意のファイル）ですが、これらのファイル群の構成とファイル中に記述されたコメントを元にします。

htmlファイルなどのソースファイルのディレクトリ構造を、そのまま目次の構造とする。
htmlファイル中に含まれるコメントに特殊な役割を持たせ、目次中のアイテムの順序や索引用語句の定義を行う。

また、「ファイルパス」と「ＩＤ」を同一にしてしまい、その扱いを簡単にします。

マップの構成

JavaHelpのマップファイルは、ファイルのパスと任意のIDを結びつける役割がありますが、この「任意のID」がそもそもくせものです。大量のファイルから構成されるJavaHelpでは、ファイルとＩＤの対応関係を覚えていられなくなると思われます。

JHGではすべてのファイルのパス及びアンカー付htmlのパスをIDとして使用します（ファイルはhtmlだけではないことに注意してください）。
例をあげます。

<mapID target="index.html" url="index.html"/>
<mapID target="index.html#Viewer" url="index.html#Viewer"/>
 <mapID target="alone/index.html" url="alone/index.html"/>
  <mapID target="alone/Files.html" url="alone/Files.html"/>
  <mapID target="alone/Files.html#Backup" url="alone/Files.html#Backup"/>
  <mapID target="alone/Guide.html" url="alone/Guide.html"/>
  <mapID target="alone/helpButton.png" url="alone/helpButton.png"/>
  <mapID target="alone/Install.html" url="alone/Install.html"/>

このようにファイルパスとＩＤは同一になります。

目次の構成

目次は基本的に、ソースファイル群のディレクトリ構造をそのまま反映したものです。

  TOP
   +-- index.html
   +-- general
   |     +-- index.html
   |     +-- GS.html
   |     +-- Support.html
   |     +-- FAQ.html
   +-- concept
         +-- index.html
         +-- Classification.html
         +-- Goods.html

このようなディレクトリ構造があった場合、JHGは次のような目次定義ファイルを出力します。

<tocitem text="商品スタッフII ヘルプ" target="index.html">
 <tocitem text="概要" target="general/index.html">
  <tocitem text="商品スタッフIIについて" target="general/GS.html"/>
  <tocitem text="サポート及びクライアント・サーバ版について" target="general/Support.html"/>
  <tocitem text="よくある質問とその答え" target="general/FAQ.html"/>
 </tocitem>
 <tocitem text="概念" target="concept/index.html">
  <tocitem text="分類" target="concept/Classification.html"/>
  <tocitem text="商品" target="concept/Goods.html"/>

targetに指定されるのは「ID」ですが、前述したようにJHGはファイルパスと同一です。

各目次アイテム(tocitem)の名称は、htmlファイルのhead部分のtitleから取得されます。また、ディレクトリ部分にあたる目次アイテムの名称は、index.htmlのtitleです。ですから、先にあげたファイルは以下のようなタイトルを持っていることになります。

  TOP
   +-- index.html                商品スタッフII ヘルプ
   +-- general
   |     +-- index.html          概要
   |     +-- GS.html             商品スタッフIIについて
   |     +-- Support.html        サポート及びクライアント・サーバ版について
   |     +-- FAQ.html            よくある質問とその答え
   +-- concept
         +-- index.html          概念
         +-- Classification.html 分類
         +-- Goods.html          商品

しかし、目次アイテムの順序の指定が必要です。そのままではgeneralディレクトリのGS.html, Support.html, FAQ.htmlをどのような順序で並べてよいのかわかりません。ファイル名のアルファベット順では不適当です。

そこで、index.htmlに特別なコメントをつけて、これらの順序を指定します。「general/index.html」には次のようなコメントを追加しています。

<!-- $TOC 
GS.html 
Support.html
FAQ.html
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<head>

最初の$TOCが目次並びの定義を示します。それに続いて、目次に表示するhtmlファイルあるいは下位のディレクトリ名を記述します。区切りは空白あるいは改行です。

索引の構成

索引ファイルを手作業で作成するのも大変なものです。JHGは、htmlファイル中に記述されたコメントを元に自動的に索引ファイルを作成します。例をあげます。

<h1>商品</h1>
<!--$INDEX 商品　しょうひん -->
<h2>概念</h2>
<p>
「商品」は本システムの中心的な役割を果たす概念です。
そのため、本システムの名称も「商品スタッフ」となっています
(「II」は次世代システムであることを象徴すべくつけられています）。
</p>
<p>
本システムでの「商品」は基本的に仕入先から仕入れ、顧客に販売するものです。
その過程でお店の利益を得ます。
利益を最大限にするためには、商品を効率的に取り扱うことが必要です。
顧客へのその他のサポートはそのような基盤があってこそ初めて可能であると思われます。
</p>

<h2><a name="Basic">商品の基本的属性</a></h2>
<p>
現実の事物をソフトウェアで扱うためには「モデル化」というものが必要です。
どのようなモデルにするのかという点は決して簡単なことではありません。
様々な試行錯誤を経て決定されるものです。
本システムでは、商品は以下のような属性を持つオブジェクトであるというモデル化を行っています。
</p>

<h3><a name="Code">商品コード</a></h3>
<!-- $INDEX 商品コード　しょうひんこーど -->
<!-- $INDEX コード、商品の　こーど、しょうひんの -->

このように$INDEXに続いて、索引語句とその読みを指定します。これらの区切りは空白ですが、空白を語句に含めたい場合は"EPSON TM-T88"のようにダブルクォートで囲みます。

JHGは索引ファイルを作成する際に、よみの頭文字ごとにまとめ、読み順にソートします。

<indexitem text="こ">
<indexitem text="顧客管理" target="concept/Customer.html"/>
<indexitem text="顧客クリップ" target="concept/Clip.html#Goods"/>
<indexitem text="顧客抽出画面" target="window/common/CustExtractor.html"/>
<indexitem text="個人" target="concept/Customer.html#Structure"/>
<indexitem text="コード、商品の" target="concept/Goods.html#Code"/>
</indexitem>

ここでもtargetに指定されるのは「ID」ですが、JHGの場合はファイルパスと同一です。また、$INDEXコメントがアンカーの後にある場合、そのアンカーが指定された形になります。

ここまでのまとめ

まとめますと、以下のようになります。

目次の構造は、ソースのディレクトリ構造と同一になる。
各htmlのタイトルが各目次タイトルになる。
index.htmlという名称のファイルは特別扱いされ、そのディレクトリの名称としてタイトルが使用されるほか、$INDEXコメントで他のファイルやディレクトリの順序を決定する。
任意のhtml中に記述された$INDEXコメントが索引として使用される。
アンカーの後の$INDEXコメントから作成された索引はそのアンカーを指す。

使用方法

本プログラムはコマンドラインから使用するようにはなっていません。適当なJavaプログラムを記述してください。最も簡単なプログラムとしては以下です。

  // ソースファイルツリーを作成
  FileTree fileTree = new FileTree(new File(".\\docs"), "Windows-31J");
      
  // JavaHelp定義ファイルジェネレータを作成
  JHFiles jhFiles = new JHFiles(fileTree)
    .setXMLEncoding("Shift_JIS")
    .setFileEncoding("Windows-31J");      
  jhFiles.createHelpSet("GSHelp.hs")
    .setHelpTitle("商品スタッフII ヘルプ")
    ;
  jhFiles.createMap("GSHelp_map.jhm");
  jhFiles.createTOC("GSHelp_toc.xml");
  jhFiles.createIndex("GSHelp_index.xml");
  jhFiles.createManifest();

  // Jarファイルを作成
  new JarGenerator(jhFiles).generate(new File(".\\GSHelp.jar"));

htmlソースのトップディレクトリとそのエンコーディングを指定してFileTreeオブジェクトを作成します。
FileTreeを指定して、ファイルジェネレータJHFilesを作成します。各ファイル（ヘルプセット、マップファイル、インデックスファイル）には名前が必要です。マニフェストファイルには不要です。
JarGeneratorを使って、JavaHelpをJarの形で出力します。

有限会社　クリプトメディア

本ソフトウェアの目的

マップの構成

目次の構成

索引の構成

ここまでのまとめ

使用方法

ナビゲーション

最近のブログ投稿

有限会社 クリプトメディア