Eclipseのヘルプ・システムを使ってプロジェクトを文書化する

使いやすく検索機能のついたヘルプ文書を構築する

Eclipseプラットフォームは非常に強力なIDEを提供するものですが、HTMLファイルを参照するXML目次に基づいた、独自のヘルプ・システムを持っています。目立たないことかも知れませんが、このヘルプ・システムを使うのにEclipseプラグインを書く必要はないのです。どんなプロジェクトでもEclipseプラットフォームからの縮小版を使って、プロフェッショナルで使いやすい、検索機能を持った形に文書化できるのです。この文書化システムはWebSphere® Application Serverのように大規模なものを含めて、いくつかのIBM®プロジェクトで成功裏に使われています。

Arthur Barr (arthur.barr at uk.ibm.com), Software engineer, IBM

Arthur BarrはUKのIBM Hursley開発研究所で働く技術者です。この記事での熟考をBusiness Integration for Gamesプロジェクトに適用し、現在そのプロジェクトに従事しているはずです。彼の連絡先は arthur.barr at uk.ibm.com です。



2004年 1月 29日

Eclipseのヘルプ・システムに(Help > Help Contentsで)アクセスすると、実際には埋め込まれたApache Tomcatサーバーを起動します。次にWebブラウザに基づいたウィンドウが開き、サーバー上にある適切なページを指します(図1)。文書は縮小表示できる目次が左側にあり、右側にHTML文書がある形で提供され、(ApacheのLuceneサーチエンジンのおかげで)いつでも検索ができるのです。Tomcatを使っているのでHTMLに限定はされません。例えばJSPを使って動的に文書を変更することもできるのです(ただし後ほど、これを避ける理由を説明するつもりですが)。

図1. Eclipseヘルプの例
図1. Eclipseヘルプの例

文書化プラグインの「Hello World」

文書は「ブック」(books)に分割され、ヘルプ・システムの1つのインスタンスは好きなだけブックを持つことができます。各ブックはEclipseプラグインとして書かれますが、幸いここでの作業はごくわずかなのです。簡単なプラグインを書くために、そのプラグインを記述するplugin.xmlファイルが必要ですが、それはリスト1のようなものになるはずです。

リスト1. プラグインの定義
<plugin name="Sample Documentation Plug-in" id="com.ibm.sample.doc"
   version="1.0.0" provider-name="IBM">
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true" />
   </extension>
</plugin>

プラグインのnameidversionそれにprovider-nameを自分のプロジェクトに適切な値に変更します。org.eclipse.help.tocの拡張ポイントはこれがヘルプ・システムへのプラグインであることを特定しています。toc.xmlファイルはこのプラグインの目次として参照されています。このファイルにはEclipseヘルプ・ウィンドウの左側の枠にある階層情報のデータが入っています。簡単なファイルには図2に示すようなものが入っています。

リスト2. 目次の定義
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html"/>
    </topic>
</toc>

プラグインをパッケージする

各トピック要素は、ナビゲーション・リストへのエントリーによって最終文書に表示されます。これらのトピックはネストされていますが(トピックが他のトピックを含む場合もあります)、各トピックはHTMLまたはJSPファイルを指します。これが終わったら、あとは全てのものを図2に示すような構造にパッケージするだけです(プラグインのディレクトリ名がplugin.xmlで定義されるプラグインのidversion属性に一致していることに注意してください)。

図2. プラグインのディレクトリ構造
図1. Eclipseヘルプの例

手軽さを図るためとファイルサイズを小さくするため、Eclipseでは実際の文書(HTMLファイル)のすべてをdoc.zipと呼ばれるZIPファイルで保存できるようになっています。ですから図3のようなディレクトリ構造が使えることになります。

図3. 別の形のプラグイン・ディレクトリ構造
図3. 別の形のプラグイン・ディレクトリ構造

文書を見る

プラグインをテストする一番簡単な方法は、単純に(上のような)ディレクトリ全体を、Eclipseプラットフォームをインストールしてあるプラグイン・ディレクトリに入れ、Eclipseを起動してHelp > Help Contentsを選択してみることです。そうすれば、そのプラグインが追加されたヘルプ・ウィンドウ(図1に示すようなもの)が見えるはずです。

テストのためにIDEを使うのは一向に構いませんが、IDE無しでも使いやすくするためには文書はもっとアクセスしやすくなっている必要があります。ですから本当に欲しいのは、文書とブラウザを結びつけて裏側で実行するプロセスです。この操作のモードはInfoCenter(図4)として知られています。InfoCenterプロセス(基本的にはApache Tomcat)の起動方法についてはEclipseヘルプ・システム文書の中に入っています(この記事の最後の参考文献にリンクがあります)。そこにはEclipseシステムから自分に必要な部分だけを切り取る方法についても説明があることに注意してください。

図4. 動作中のInfoCenter
図4. 動作中のInfoCenter

大きな目次を扱う

もしプロジェクトに携わる人が数人以上の場合、または文書セットが大きい場合には単一の目次ファイル(toc.xml)を更新するのは現実的ではなくなってきます。これはメインのtoc.xmlファイルにあるトピックに、link要素を追加することで変更できます(一例をリスト3に示します)。

リスト3. 目次の定義
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html">
            <link toc="bar-toc.xml" />
        </topic>
    </topic>
</toc>

bar-toc.xmlファイルは単にもう一つの目次にすぎず、他のどんなtoc.xmlファイルとも全く同じような形式をとるはずです。この方法を使って文書を見るのと、topic要素を直接追加した方法で見るのとに全く差はありません。


独立の文書セットを生成する

当然ながら、20MB以上ものコードを配布することを気にしないのであればEclipseのヘルプ・システムを使っても一向構いませんが、小さなプロジェクトには現実的ではありません。中央のサーバーでInfoCenterを集約することにより、ユーザーが遠隔から接続できるようになります。こうするとEclipseのヘルプ・システムの恩恵のすべて(検索など)を享受できますが、接続されていないユーザーは置いてきぼりになります。ですから集約したInfoCenterを使うだけでなく、ダウンロード・パッケージに単純なHTMLを入れておくと有効です。JSPのような、サーバー側の技術を使っていなければ、HTMLの目次を生成してXMLの目次と置き換えるのは容易です。これがXSLTを使う理由なのです。

XSLT (eXtensible Stylesheet Language Transformations)は、あるXMLの形式を別の形式(例えばより厳密な、XML版のHTMLであるXHTMLなど)に変換するために使われる技術です。XSLTには変換のための豊富で強力な言語がありますが、それらに関しては多くの本や記事が書かれているので、ここではその詳細に触れません。リスト4はtoc.xmlファイルを単純に変換したもので、ネストされたHTMLリストとしてエントリーをレンダリングしたものです。注意して欲しいのですが、この例の変換では文書セット全体の目次に対して単一のHTMLファイルを作成するので、ファイル数が多いと動きが悪くなります。ですからこのXSLTは、目次を複数ファイルに分割してある場合には動作しません。

リスト4. HTMLの目次を生成するXSLTの例
<?xml version="1.0"?>
<xsl:stylesheet
   version="1.1"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="no" encoding="ISO-8859-1" />
<xsl:template match="toc">
   <html>
      <head />
      <body>
         <h1><xsl:value-of select="@label" /></h1>
         <ul>
            <xsl:apply-templates />
         </ul>
      </body>
   </html>
</xsl:template>
<xsl:template match="topic">
   <li>
      <xsl:choose>
         <xsl:when test="@href">
            <!-- Only add a hyperlink when there is something to link to ->
            <xsl:element name="a">
               <xsl:attribute name="href">
                  <xsl:value-of select="@href" />
                  </xsl:attribute>
               <xsl:value-of select="@label" />
            </xsl:element>
         </xsl:when>
         <xsl:otherwise>
            <xsl:value-of select="@label" />
         </xsl:otherwise>
      </xsl:choose>
      <!-- If there are any nested topics, then start a new sub-list ->
      <xsl:if test="descendant::topic">
         <ul>
            <xsl:apply-templates/>
         </ul>
      </xsl:if>
   </li>
</xsl:template>
</xsl:stylesheet>

上のXSLTを使ってApache XalanのようなXSLTプロセッサーでtoc.xmlファイルを処理すると、ブラウザで図5のように見えるHTMLファイルが生成されます。

図5. 生成されたindex.html
図5. 生成されたindex.html

まとめ

Eclipseのヘルプ・システムを使うことで、友人や同僚を驚かすほどプロフェッショナルな見栄えと検索機能を持った文書が手軽に開発できます。独立の文書セットが必要無い場合であれば、XSLTに頼る必要さえ無いのです。簡単なXMLファイルを2つ書きさえすれば、幸福なる文書の世界に旅立てるのです。

参考文献

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Open source
ArticleID=236416
ArticleTitle=Eclipseのヘルプ・システムを使ってプロジェクトを文書化する
publish-date=01292004