ヘルプ作成のノウハウ

提供: MacWiki
移動: 案内検索

アプリケーションの HTML ヘルプを作る(&索引を作成して検索に対応させる)

検索用のインデックス[編集]

Mac OS X 10.0 〜 10.3.x までと Mac OS X 10.4 以降とではやや異なる部分がありますが、 大雑把に言ってしまえば、 索引作成用のアプリケーションが違う、 というだけのことだと思います。

  • Mac OS X 10.0 〜 10.3.x ── Apple Help Indexing Tool.app を使用。
    • /Developer/Documentation/Apple Help/Apple Help Indexing Tool.app
  • Mac OS X 10.4 ── Help Indexer.app を使用。
    • /Developer/Applications/Utilities/Help Indexer.app

Help Indexer.app を使うと、 10.4 以降用の索引ファイル(.helpindex ファイル)と同時に、 10.0 〜 10.3.x の索引ファイル(idx ファイル)を作成することができます。 ちなみに旧来の Apple Help Indexing Tool.app は、 10.4 Tiger 上では起動させることができませんでした。

ヘルプブックの作成について[編集]

TeXShopの日本語ヘルプ作成で必要となった事項に限定して記述しています (さらに高度なこともできるようですが、それについては省略しています)。 メタタグについても、使用しなかったものについては言及していません。

おおまかな作業過程[編集]

  • ヘルプのコンテンツを用意する──訳文、日本語版用テキスト、画像など。
  • HTML化する──いちおう HTML3.2準拠。
  • メタタグの記述──各htmlファイルのヘッダ部分に、必要に応じて。
  • 索引を作成する── Apple Help Indexing Tool.app ないしは Help Indexer.app を使用。

ファイル構成[編集]

  • ファイル構成についての注意点
    • 全体を1つのフォルダにまとめる。
    • フォルダ内の最上位の階層に基点となるページ(タイトルページ)を置く。
  • ちなみに「TeXShopHelp (v1.34)」のファイル構成は以下のようになっています。
    • TeXShopHelp <----- 全体をまとめるフォルダ
      • gfx <----- 画像ファイルを入れたサブフォルダ
        • bmA.gif
        • scA.gif
        • scic.gif <----- ヘルプセンターのリストで表示される小さなアイコン
        • xicnsc.gif
      • pgs <----- ヘルプ項目ごとのページを入れたサブフォルダ
        • 〜.htm
        • 〜.htm
        • 〜.htm
        • 以下多数
      • TeXShop Help.html <----- 基点となるページ(タイトルページ)
      • TeXShopHelp idx <----- Apple Help Indexing Tool が生成する idxファイル

メタタグの記述[編集]

  • 「TeXShop ヘルプ」のタイトルページのヘッダは次のようにしました。
<HEAD>
	<META HTTP-EQUIV="content-type" CONTENT="text/html;charset=Shift_JIS">
	<TITLE>TeXShop ヘルプ</TITLE>
	<META NAME="AppleTitle" CONTENT="TeXShop ヘルプ">
	<META NAME="AppleIcon" CONTENT="TeXShopHelp/gfx/scic.gif">
	<META NAME="AppleFont" CONTENT="Lucida Grande,Helvetica,ヒラギノ角ゴ Pro W3">
		<META NAME="AppleSearchResultsFont" CONTENT="Lucida Grande,Helvetica,ヒラギノ角ゴ Pro W3">
	<META NAME="robots" CONTENT="NOINDEX">
</HEAD>
    • 文字エンコーディングの指定
      • 10.1以降のヘルプビューワではエンコーディング指定を順守します。
      • 日本語ヘルプを作成する場合は「Shift_JIS」にする必要があります。
        • UTF-8にした場合は、ヘルプを見ることは問題ありませんが、日本語部分の索引が作成されません。よって検索もできませんでした。
        • 英語版のエンコーディング「iso-8859-1」を指定する部分をヘッダ内にコメントアウトの形で残しておくと、ヘルプ本文の表示には問題ないものの、ヘルプビューワのライブラリメニュー内と検索結果画面で ASCII 文字以外すべて文字化けします。
    • AppleTitle
      • ヘルプブックのタイトルです。
      • この中身と InfoPlist.strings の中身 : CFBundleHelpBookName = "TeXShop ヘルプ" を一致させておきます。(Koch さんは暫定的に Help に直しているようです)
    • AppleIcon
      • ヘルプブック用のアイコン画像ファイルを指定しています。
    • AppleFont
      • ヘルプセンターでリスト表示される時のフォントを指定。Osaka なども可とのこと。
    • AppleSearchResultsFont
      • 検索結果を表示するフォントを指定。Osaka なども可とのこと。
  • 索引作成は基本的にページ全体に対して行なわれますが、"ROBOTS" を使うことで索引対象を指定できます。
<META NAME="ROBOTS" CONTENT="NOINDEX">
    • これが書き込まれたファイルについては、索引を作成しないように指定しています──リンク集や画像だけのページ、あるいは扉や目次などのページなどに書いておくようです。
  • TeXShophelp/pgs/ 内にある、ヘルプ項目ごとの htmファイルで使われているメタタグはおおむね次のようなものです。
<META NAME="copyright" CONTENT="Copyright (c) 2003 Richard Koch under the GNU FDL">
    • 著作権表示のようですが、ヘルプビューワで実際に表示されるのかどうかは確認できませんでした。
<META NAME="DESCRIPTION" CONTENT="______">
    • ___部分にそのページの概要を書いておきます。検索結果画面で項目を選択した場合に、下のほうに表示されます。この記述がない場合には「概要が用意されていません」と表示されます。
    • すべてのhtmファイルのヘッダに <META HTTP-EQUIV="content-type" CONTENT="text/html;charset=Shift_JIS"> を付加しました。
      • Shift JIS では、半角バックスラッシュ( \ )と円記号( ¥ )を区別できなくなりますね。表現上の工夫で対応できますか?
      • 2つを書き分ける必要がある場合(日本語エンコーディング方式の説明など)では、ユニコードタグを使って「 \ 」=「 \ 」「 ¥ 」=「 ¥ 」としておきました。

Apple Help Indexing Tool の使用 (旧来の方法)[編集]

  • Apple の Developer Tools をインストールしていれば、Developer > Documentation > AppleHelp > にあります。
  • 日本語の場合、Apple Help Indexing Tool を起動したら、まずメニューから「環境設定...」を選択します。
  • 次にパネル内の「Japanese plug-in tokenizer」のラジオボタンをチェックしてOKを押します。
  • 索引の作成( indexing )はヘルプフォルダを Apple Help Indexing Tool のアイコンにドロップして行ないます。
  • プログレスバーを含むウィンドウが現われます。ウィンドウ内の表示が文字化けしていても問題はないようです。
  • 「TeXShopHelp」フォルダ内のタイトルページと同じ階層に、TeXShopHelp idx が生成されます。
    • 注意:ヘルプブック内のファイルを変更すると、この idxファイルは無効となります。変更した場合は改めて索引の作成を行ないます。

Help Indexer.app の使用(Mac OS X 10.4 Tiger)[編集]

  • Apple の Developer Tools をインストールしていれば、Developer > Applications > Utilities > にあります。
  • Help Indexer.app を起動したら、まずメニューから「環境設定...」を選択します。
  • 日本語の場合、右上にある「Minimum term length」の項目をプルダウンメニューで「1 token」にします。
  • 10.4 以前の索引ファイルも同時に作成したい場合には、左側の「Generate Panther-compatible Indices」にチェックを入れ、プルダウンメニューから「Japanese」を選択します。
  • OKボタンを押して環境設定パネルを閉じます。
    • この設定はアプリケーション終了後は完全には保持されないので、使用ごとに設定しなおす必要があります。
  • ヘルプファイルの入ったフォルダを選択し、索引の作成( indexing )を行ないます。
  • 「TeXShopHelp」フォルダ内のタイトルページと同じ階層に、TeXShopHelp.helpindex が生成されます(10.4 以前の索引作成も選択していれば TeXShopHelp idx も生成されます)。
  • 「Quit」を押して終了します。
    • 注意:ヘルプブック内のファイルを変更すると、この .helpindex ファイルおよび idxファイルは無効となります。変更した場合は改めて索引の作成を行ないます。


ヘルプブックの置き場所[編集]

  • 次のいずれかに置けば検索可能になり、ヘルプビューワのライブラリメニューにも登録されます。
    • アプリケーションの Japanese.lproj の中。
    • /Library/Documentation/Help
    • ~/Library/Documentation/Help
  • 拡張子「.help」付きは Apple だけが使用できる(?)。

参照した主なドキュメントへのリンク[編集]

Wiki内の関連ページ[編集]